Command+Z for Your Terminal - Never Lose Track of What Happened
- The Problem
- The Solution
- Key Features
- Quick Start
- Installation
- Usage
- Real-World Scenarios
- How It Works
- Use Cases
- Integration
- Configuration
- Troubleshooting
- Contributing
- Credits
- License
When working in the terminal, critical information is constantly lost:
- "What command caused this error?" - Lost in scrollback history
- "How did I break this?" - No way to trace back through your actions
- "What did the last agent do?" - Agent handoffs lose critical context
- "I need to reproduce this bug" - Can't remember exact steps
- "Someone ran rm -rf" - Files gone forever
- No undo for terminal - Unlike text editors, no Ctrl+Z
- Destructive commands are irreversible - One mistake can cost hours
- Manual note-taking - Tedious, incomplete, forgotten
- history command - Only commands, no outputs, no timestamps
- Screen recording - Not searchable, huge files
Result: Debugging is painful, mistakes are costly, and agent coordination suffers.
TerminalRewind treats your terminal like a rewindable video:
BEFORE AFTER
┌──────────────────────────┐ ┌──────────────────────────┐
│ Terminal is a │ │ Terminal is a │
│ BLACK BOX │ → │ REWINDABLE VIDEO │
│ │ │ │
│ • Commands forgotten │ │ • Every command saved │
│ • Outputs lost │ │ • Full output recorded │
│ • No undo possible │ │ • Rollback available │
│ • Context lost │ │ • Perfect handoffs │
└──────────────────────────┘ └──────────────────────────┘
- Records Everything - Commands, outputs, exit codes, timestamps
- Tracks File Changes - Which files were created, modified, deleted
- Enables Replay - See exactly what happened step-by-step
- Provides Undo - Rollback destructive commands
- Powers Handoffs - Export sessions for AI agents or team members
Record every command with full context:
- Timestamp (when it ran)
- Working directory (where it ran)
- Exit code (did it succeed?)
- Full output (what did it produce?)
- Duration (how long did it take?)
Know exactly what each command did to your files:
- Files created
- Files modified (with before/after hashes)
- Files deleted
- Automatic backups for rollback
Find any command instantly:
trewind search "npm install" # Find all npm installs
trewind search "error" # Find commands with errors
trewind show --errors # Show only failed commandsUndo destructive commands:
trewind undo --dry-run # Preview what would be restored
trewind undo --apply # Actually restore filesPerfect for AI agent coordination:
trewind export --for-agent CLIO > handoff.mdGenerates comprehensive context for the next agent.
Organize work into sessions:
trewind start --name "Bug Fix" --agent ATLAS
# ... do work ...
trewind endgit clone https://github.com/DonkRonk17/TerminalRewind.git
cd TerminalRewind
pip install -e .# Start a new session
trewind start --name "My Work Session"
# Log commands as you work
trewind log "git status" --exit-code 0
trewind log "npm install" --exit-code 0 --output "added 500 packages"trewind show # Show recent commands
trewind show --limit 50 # Show last 50 commands
trewind show --errors # Show only failurestrewind export --for-agent CLIO > handoff.mdThat's it! You now have a complete record of your terminal session.
git clone https://github.com/DonkRonk17/TerminalRewind.git
cd TerminalRewind
pip install -e .git clone https://github.com/DonkRonk17/TerminalRewind.git
# Add to your PATH or create an alias
alias trewind="python /path/to/terminalrewind.py"- Python 3.8+
- No external dependencies (uses only stdlib)
trewind --version
# Output: TerminalRewind v1.0.0trewind log "git commit -m 'feature'" --exit-code 0
trewind log "npm test" --exit-code 1 --error "2 tests failed"trewind record "ls -la" --execute
trewind record "cat file.txt" --execute --track-filestrewind record "python script.py" --execute --track-files
# Tracks all file changes in current directorytrewind show # Last 20 commands
trewind show --limit 100 # Last 100 commands
trewind show --verbose # Include file changestrewind show --since "10 minutes ago"
trewind show --since "1 hour ago"
trewind show --since "2026-01-31T10:00:00"trewind show --errors # Only failed commands
trewind show --session abc123 # Only from specific sessiontrewind search "npm" # Commands containing "npm"
trewind search "error" # Commands with "error" in output
trewind search "git commit" # Find git commitstrewind search "install" --verbose # Include output snippets
trewind search "build" --limit 50 # More resultstrewind export --format markdown > session.md
trewind export --session abc123 --format markdowntrewind export --format json > session.jsontrewind export --for-agent CLIO > handoff_for_clio.md
trewind export --for-agent ATLAS --limit 30trewind undo --dry-run # Shows what would be restored
trewind undo 123 --dry-run # For specific command IDtrewind undo --apply # Restore files from last command
trewind undo 123 --apply # Restore files from command #123Perfect for multi-agent workflows:
# Agent 1 (ATLAS) finishes work
trewind end
trewind export --for-agent CLIO > handoff.md
# Agent 2 (CLIO) reviews handoff
cat handoff.md
# Sees: complete command history, errors, file changestrewind start --name "Bug Fix Sprint"
trewind start --name "Feature Development" --agent ATLAStrewind endtrewind sessions
trewind sessions --limit 20trewind statsOutput:
=== TerminalRewind Statistics ===
Total Commands: 1,234
Successful: 1,180
Failed: 54
Success Rate: 95.6%
Total Sessions: 47
File Changes: 892
Database: ~/.local/share/TerminalRewind/terminalrewind.db
Database Size: 2.34 MB
Situation: Logan asks ATLAS to start a feature, then CLIO to finish it.
Without TerminalRewind:
- CLIO has no idea what ATLAS did
- Starts from scratch or guesses
- Wastes time retracing steps
With TerminalRewind:
# ATLAS finishes and exports
trewind export --for-agent CLIO > handoff.md
# CLIO reads the handoff
cat handoff.md
# Sees every command, output, file change
# Continues seamlessly from where ATLAS left offSituation: Build suddenly breaks, no idea why.
Without TerminalRewind:
- Scroll through terminal history
- Guess what changed
- Spend 30+ minutes debugging
With TerminalRewind:
trewind show --since "1 hour ago" --errors
# Immediately see: which command failed, what error occurred
# Identify the culprit in secondsSituation: Accidentally ran rm -rf important_folder/
Without TerminalRewind:
- Files gone forever (unless git committed)
- Restore from backup (if you have one)
With TerminalRewind:
trewind undo --apply
# Files restored from pre-command snapshot
# Crisis averted!Situation: "How did you fix that bug?"
Without TerminalRewind:
- "Umm... I changed some files..."
- Manual reconstruction from memory
With TerminalRewind:
trewind export --format markdown > fix_documentation.md
# Complete step-by-step documentation with:
# - Every command
# - All outputs
# - File changes
# - Timestamps┌─────────────────────────────────────────────────────────────┐
│ TerminalRewind │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Recorder │ │ Tracker │ │ Exporter │ │
│ │ │ │ │ │ │ │
│ │ - Log cmds │ │ - Watch files│ │ - JSON │ │
│ │ - Execute │ │ - Detect ∆ │ │ - Markdown │ │
│ │ - Track │ │ - Backup │ │ - Agent │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └───────────────────┼───────────────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ SQLite DB │ │
│ │ │ │
│ │ - commands │ │
│ │ - file_changes │ │
│ │ - sessions │ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
commands - Every recorded command
- id, session_id, timestamp, command, cwd
- exit_code, output, error_output, duration_ms
- platform, shell, user, hostname
file_changes - Files affected by commands
- command_id, file_path, change_type
- old_hash, new_hash, backup_path
sessions - Logical groupings of work
- id, name, started_at, ended_at
- command_count, success_count, error_count
- Before command: Snapshot current file hashes
- Execute command: Run the actual command
- After command: Compare new hashes
- Backup: Save originals for rollback
- Record: Store changes in database
- Session continuity - Resume where you left off
- Perfect handoffs - Next agent sees everything
- Error debugging - Trace back through failures
- Audit trail - Complete record of actions
- Bug reproduction - Exact steps to reproduce
- Documentation - Auto-generated session docs
- Pair programming - Share what you did
- Learning - Review your own patterns
- Incident response - What commands led to this?
- Change tracking - What changed and when?
- Compliance - Complete audit trail
- Recovery - Rollback destructive changes
from synapselink import quick_send
from terminalrewind import SessionExporter, TerminalRewindDB
db = TerminalRewindDB()
exporter = SessionExporter(db)
# After completing a task
handoff = exporter.for_agent("CLIO")
quick_send("CLIO", "Session Handoff", handoff)from agenthealth import AgentHealth
from terminalrewind import CommandRecorder
health = AgentHealth()
recorder = CommandRecorder()
# Track health alongside commands
health.start_session("ATLAS")
recorder.start_session(agent_name="ATLAS")
# ... work ...
health.end_session("ATLAS")
recorder.end_session()Terminal sessions can be logged to BCH for team visibility:
# Export and send to BCH channel
export = exporter.to_json()
bch.send_message("terminal-logs", export)See INTEGRATION_PLAN.md for full integration details.
Default: ~/.local/share/TerminalRewind/terminalrewind.db
Custom:
from terminalrewind import TerminalRewindDB
db = TerminalRewindDB(Path("/custom/path/db.sqlite"))Default: ~/.local/share/TerminalRewind/backups/
# Custom database path
export TERMINALREWIND_DB=/path/to/db.sqlite
# Disable auto-session
export TERMINALREWIND_AUTO_SESSION=falseProblem: Multiple processes accessing database
Solution:
# Close other trewind processes
# Or use a different database file
trewind --db /tmp/session.db showProblem: Can't write to backup directory
Solution:
# Check permissions
ls -la ~/.local/share/TerminalRewind/
# Or use custom backup dir
export TERMINALREWIND_BACKUP_DIR=/tmp/backupsProblem: Database is empty or session not started
Solution:
# Start a session first
trewind start --name "Test"
# Then log commands
trewind log "echo hello"Problem: Database growing too large
Solution:
# Export important sessions
trewind export --session important > backup.json
# Compact database (manual)
sqlite3 ~/.local/share/TerminalRewind/terminalrewind.db "VACUUM"
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch
- Write tests for new functionality
- Follow the code style (type hints, docstrings)
- Submit a pull request
- Type hints for all functions
- Docstrings for public methods
- No emojis in Python code (ASCII-safe)
- Tests required for new features
python test_terminalrewind.pyBuilt by: ATLAS (Team Brain)
For: Logan Smith / Metaphy LLC
Requested by: IRIS via Synapse TOOL_REQUEST
Why: Enable terminal undo, agent handoffs, and complete session tracking
Part of: Beacon HQ / Team Brain Ecosystem
Date: January 31, 2026
Trophy Potential: LEGENDARY (50+ points) - Novel concept, high impact, foundational tool
- IRIS for the original TOOL_REQUEST and vision
- Forge for orchestration and review
- The Team Brain collective for testing and feedback
MIT License - See LICENSE for details.
- EXAMPLES.md - Comprehensive usage examples
- CHEAT_SHEET.txt - Quick reference guide
- INTEGRATION_PLAN.md - Team Brain integration
- QUICK_START_GUIDES.md - Agent-specific guides
Built with precision, deployed with pride.
Together for all time! 🔥