Terminal State Restore (TSR)

A lightweight CLI tool written in Go to track, capture, and restore terminal state. Prevent terminal corruption and session loss with automatic state snapshots and monitoring.

Features

• Capture Terminal State - Save snapshots of your terminal environment (working directory, environment variables, system info)
• Restore Terminal State - Quickly restore a previously saved terminal state
• List Saved States - View all saved terminal state snapshots
• Monitor Terminal State - Continuously monitor for terminal state changes and auto-save checkpoints
• Shell Integration - Easy integration with bash and zsh shells
• POSIX Compliant - Respects POSIX standards for maximum compatibility
• Zero Dependencies - Pure Go implementation

Installation

Download Binary

Pre-compiled binaries are available for releases.

Build from Source

git clone https://github.com/mosleyit/terminal-state-restore.git
cd terminal-state-restore
go build -o tsr .
sudo mv tsr /usr/local/bin/

Usage

Basic Commands

# Capture current terminal state
tsr capture my-session

# List all saved states
tsr list

# Restore a saved state
tsr restore my-session

# Monitor terminal state (runs in background)
tsr monitor

# Show help
tsr help

Shell Integration

Bash

Add to your ~/.bashrc:

eval "$(tsr init --shell bash)"

Or manually add the integration:

# Capture state before exiting on error
tsr_save_on_exit() {
    local exit_code=$?
    if [ $exit_code -ne 0 ]; then
        tsr capture "exit-$exit_code-$(date +%s)" 2>/dev/null
    fi
    return $exit_code
}

# Uncomment to enable:
# trap tsr_save_on_exit EXIT

Zsh

Add to your ~/.zshrc:

eval "$(tsr init --shell zsh)"

Advanced Usage

Auto-save on Error

Enable automatic state capture when commands fail:

trap 'tsr capture "exit-$?-$(date +%s)" 2>/dev/null' EXIT

Background Monitoring

Start monitoring in the background:

tsr monitor --interval 30s &

This will automatically create checkpoints whenever terminal state changes.

Restore with Directory Change

# Restore state and change to saved working directory
tsr restore my-session
cd "$(tsr restore my-session | grep 'Working directory' | cut -d' ' -f3)"

State Information Captured

Each terminal state snapshot includes:

• Working Directory: Current working directory
• Environment Variables: All environment variables
• System Info: Username, hostname, shell type
• Timestamp: When the state was captured
• Shell History: (Extensible for future versions)
• Aliases: (Extensible for future versions)
• Functions: (Extensible for future versions)

Storage

Terminal states are stored in ~/.terminal-state-restore/ as JSON files:

~/.terminal-state-restore/
├── my-session.json
├── exit-1-1729776444.json
└── checkpoint-1729776500.json

Each file is readable and can be inspected manually:

cat ~/.terminal-state-restore/my-session.json

Testing

Run the test suite:

go test -v ./...

Tests cover:

• State capture and serialization
• Storage operations (save, load, list, delete)
• System information capture
• JSON marshaling/unmarshaling

Use Cases

1. Debugging Failed Commands - Capture state when commands fail for later analysis
2. Session Recovery - Restore your terminal environment after crashes
3. Development Workflows - Save and restore project-specific environments
4. CI/CD Integration - Monitor and verify terminal state in automated scripts
5. Terminal Corruption Prevention - Detect and prevent terminal state corruption

Limitations

• Shell history capture not yet implemented
• Aliases and functions require manual restoration via shell integration
• Currently supports bash and zsh (other shells can be added)

License

MIT - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit pull requests.

Author

Jeff Mosley - GitHub