claude-rewind

Claude Rewind

A Git-powered session backup tool for Claude Code with complete change tracking and advanced restore capabilities. Uses an isolated Git repository for backups - never touches or interferes with your project's Git environment.

Features

• Git-Powered Core: Every backup is a Git commit with full change history in an isolated repository
• Zero Project Impact: Uses dedicated .claude-sessions/backup-repo - your project's Git remains untouched
• Advanced Comparisons: Compare any two backup sessions to see exact differences
• Smart Restore: Restore only changed files or specific file sets
• File History: Track the complete change history of individual files
• Natural Language Interface: MCP integration with intuitive commands like "compare recent sessions"
• Conflict Detection: Intelligent restore with conflict detection and resolution
• Branch Safety: Automatic branch consistency checks with user confirmation for cross-branch restores

Quick Start

🚀 Global Installation (Recommended)

npm install -g claude-rewind
claude-rewind-install

Prerequisites: Git must be installed and configured on your system.

⚡ Try Without Installing

npx claude-rewind-quick     # Smart auto-setup
npx claude-rewind backup    # Create backup
npx claude-rewind list      # List sessions
npx claude-rewind restore last  # Restore latest

📁 Project-specific Installation

npm install claude-rewind
npx claude-rewind-install

How It Works

Claude Rewind automatically creates Git commits of your project files when Claude Code sessions end. Each backup is stored as a commit in a dedicated, isolated Git repository (.claude-sessions/backup-repo) that operates completely independently from your project's Git repository.

Key Architecture:

• Isolated Environment: Uses its own Git repository with dedicated user configuration
• Zero Pollution: Never modifies, commits to, or interferes with your project's Git history
• Git-Native Benefits: Full change tracking, compression, and Git's proven versioning capabilities
• Project Metadata: Captures your project's Git status (branch, commit, dirty state) as reference only

Automatic Integration

After installation, Claude Rewind seamlessly integrates with Claude Code:

• Session-Start Hook: Automatically initializes new projects
• Session-End Hook: Creates backups when sessions complete
• Smart .gitignore: Auto-updates Git projects to exclude backup directories
• Project Detection: Adapts to different project types (npm, python, etc.)

Slash Commands

Use these commands directly in Claude Code:

• /rewind:status - Show backup system status
• /rewind:list [count] - List recent backup sessions
• /rewind:backup - Create manual backup
• /rewind:restore <session_id> - Restore to specific session
• /rewind:info <session_id> - Show session details
• /rewind:delete <session_id> - Delete backup session

CLI Commands

After Global Installation

Basic Commands:

claude-rewind backup                    # Create backup
claude-rewind list [count]              # List sessions  
claude-rewind restore <session_id>      # Restore session
claude-rewind info <session_id>         # Session details
claude-rewind delete <session_id>       # Delete session
claude-rewind status                    # System status

Git-Enhanced Commands:

claude-rewind diff <session1> <session2>  # Compare two sessions
claude-rewind history <file_path>         # Show file change history
claude-rewind smart-restore <session_id>  # Restore only changed files

# Branch safety options for restore commands
claude-rewind restore <session_id> --ignore-branch  # Skip branch mismatch warnings
claude-rewind restore <session_id> --force         # Override all conflicts and warnings
claude-rewind smart-restore <session_id> --ignore-branch  # Skip branch checks for smart restore

NPX Commands (No Installation Required)

npx claude-rewind backup               # Create backup
npx claude-rewind list                 # List sessions
npx claude-rewind restore last         # Restore latest
npx claude-rewind status               # Check status
npx claude-rewind-install              # Setup wizard
npx claude-rewind-quick                 # Smart auto-setup

MCP Integration

Claude Rewind includes Model Context Protocol support for natural language operations:

Basic Operations:

"show backup status"
"list recent 5 backups"
"create new backup"
"restore to latest backup"

Git-Enhanced Operations:

"compare recent sessions"
"show file history: src/main.js"
"smart restore to latest backup"

The MCP server is automatically configured during installation.

Programmatic Usage

const { BackupEngine, RestoreEngine } = require('claude-rewind');

// Create backup (Git commit)
const backupEngine = new BackupEngine();
const result = await backupEngine.createBackup();

// List sessions
const restoreEngine = new RestoreEngine();
const sessions = await restoreEngine.listSessions(10);

// Compare sessions
const comparison = await restoreEngine.compareBackups('session1', 'session2');

// Get file history
const history = await restoreEngine.getFileHistory('src/main.js');

// Smart restore (only changed files)
const smartResult = await restoreEngine.smartRestore('last');

// Regular restore
const restoreResult = await restoreEngine.restoreSession('last');

File Filtering

Claude Rewind automatically ignores common directories and files:

• node_modules/**, .git/**, dist/**, build/**
• Log files (**/*.log), environment files (.env, .env.*)
• Temporary files (*.tmp, *.temp)
• System files (.DS_Store, Thumbs.db)

Troubleshooting

Installation Issues:

• Ensure Git is installed and configured: git --version
• Use sudo npm install -g claude-rewind if permission errors occur
• Ensure npm bin directory is in your PATH

Git-Related Issues:

• Check Git configuration: git config --list
• Backup repository located at .claude-sessions/backup-repo
• Use git log in backup repo to see commit history

Backup Issues:

• Check logs in .claude-sessions/logs/ for details
• Git compression provides automatic space optimization
• Large files (>100MB) are tracked but may affect performance

Common Solutions:

• Permission errors: Ensure write access to project directory
• Git errors: Check Git installation and configuration
• Repository corruption: Backup repo can be re-initialized safely

License

Apache 2.0

Quick Commands:

• Install: npm install -g claude-rewind
• Try: npx claude-rewind-quick
• Setup: claude-rewind-install
• Backup: claude-rewind backup
• List: claude-rewind list
• Restore: claude-rewind restore last