Lightweight session backup management tool for Claude Code using hardlinks for zero-disk-overhead backups
npm install 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.
- 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
``bash`
npm install -g claude-rewind
claude-rewind-install
Prerequisites: Git must be installed and configured on your system.
`bash`
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
`bash`
npm install claude-rewind
npx claude-rewind-install
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
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.)
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
- - Restore to specific session/rewind:info
- - Show session details/rewind:delete
- - Delete backup session
Basic Commands:
`bash`
claude-rewind backup # Create backup
claude-rewind list [count] # List sessions
claude-rewind restore
claude-rewind info
claude-rewind delete
claude-rewind status # System status
Git-Enhanced Commands:
`bash
claude-rewind diff
claude-rewind history
claude-rewind smart-restore
$3
bash
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:
bash
"show backup status"
"list recent 5 backups"
"create new backup"
"restore to latest backup"
`Git-Enhanced Operations:
bash
"compare recent sessions"
"show file history: src/main.js"
"smart restore to latest backup"
`The MCP server is automatically configured during installation.
Programmatic Usage
javascript
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:
-
, .git/, dist/, build/
- Log files (), 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 if permission errors occur
- Ensure npm bin directory is in your PATHGit-Related Issues:
- Check Git configuration:
git config --list
- Backup repository located at
- Use in backup repo to see commit historyBackup Issues:
- Check logs in
.claude-sessions/logs/ for details
- Git compression provides automatic space optimization
- Large files (>100MB) are tracked but may affect performanceCommon 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:
- Setup:
- Backup:
- List:
- Restore: