Checkpoint Manager for Claude Code

The /checkpoint-manager command helps you manage Claude Code's automatic checkpointing system to safely rewind changes, explore alternatives, and code without fear.

Features

• Automatic Checkpoints: Snapshots saved before every Claude-driven file edit
• Quick Rewind: Press ESC+ESC or use /rewind to access checkpoint menu
• Selective Restore: Restore code only, conversation only, or both
• Change Preview: See exactly what will be reverted before confirming
• Session-Level Recovery: Checkpoints tracked within current session
• Manual Checkpoints: Create named checkpoints at critical points
• Checkpoint History: View all checkpoints with timestamps and descriptions
• Safe Exploration: Try risky changes knowing you can rewind

Usage

/checkpoint-manager [action] [options]

Actions

• --rewind - Open checkpoint menu to restore previous state
• --create - Manually create named checkpoint
• --list - Show all checkpoints in current session
• --preview - Preview changes that will be reverted
• --auto-checkpoint - Configure automatic checkpoint settings

Restore Options

• --code-only - Revert file changes, keep conversation
• --conversation-only - Rewind conversation, keep code changes
• --both - Restore both code and conversation (default)

Checkpoint Settings

• --enable-auto - Enable automatic checkpointing (default: true)
• --disable-auto - Disable automatic checkpointing
• --interval=<n> - Create checkpoint every N file edits

Quick Access

ESC+ESC Method (Fastest)

# During any Claude Code session:
# Press ESC twice quickly

[Checkpoint Menu]
┌─────────────────────────────────────────────┐
│ Rewind to Previous State                    │
├─────────────────────────────────────────────┤
│ 1. [2 min ago] Added user authentication    │
│    Files: auth.service.ts, user.model.ts    │
│                                             │
│ 2. [5 min ago] Fixed login validation      │
│    Files: auth.service.ts                   │
│                                             │
│ 3. [12 min ago] Created auth endpoint       │
│    Files: routes/auth.ts                    │
├─────────────────────────────────────────────┤
│ [R] Restore Code Only                       │
│ [C] Restore Conversation Only               │
│ [B] Restore Both                            │
│ [ESC] Cancel                                │
└─────────────────────────────────────────────┘

/rewind Command Method

/rewind

# Opens same checkpoint menu
# Select checkpoint by number
# Choose restore type

Examples

Basic Rewind Workflow

Scenario: Risky refactoring went wrong

User: "Refactor the payment service to use async/await"

Claude: *refactors 15 files*

[Automatic Checkpoint Created]
Snapshot: Before payment service refactor
Files: 15 modified

User: *tests application*
User: "The payment flow is broken now"

# Press ESC+ESC

[Checkpoint Menu]
1. [1 min ago] Refactored payment service
   Files: payment.service.ts, payment.controller.ts, ...

Select: 1
Restore: [B] Both code and conversation

✓ Restored to checkpoint
✓ 15 files reverted
✓ Conversation rewound to before refactor

Claude: "Reverted to before payment service refactor. Would you like to try a different approach?"

Code-Only Restore (Keep Conversation)

Scenario: Want to keep discussion but undo code changes

Claude: *implements feature with extensive discussion*

User: "Actually, I prefer the old implementation"

/rewind

[Select Checkpoint]
1. [5 min ago] Implemented notification system
   Files: notification.service.ts, email.template.ts

Select: 1
Restore: [R] Code Only

✓ Code reverted to checkpoint
✓ Conversation preserved

Claude: "I've reverted the code changes but kept our discussion. Based on our conversation, would you like me to implement it differently?"

Conversation-Only Restore

Scenario: Code is good, but conversation went off track

Claude: *correct implementation but confusing discussion*

User: "The code is fine, but let's restart the conversation"

/rewind

Select: 2. [10 min ago] Started authentication implementation
Restore: [C] Conversation Only

✓ Conversation rewound
✓ Code changes preserved

Claude: "Let's start fresh. What would you like to work on?"

Manual Checkpoint Creation

Scenario: Before making risky database migration

User: "I'm about to migrate the database schema"

/checkpoint-manager --create "Before database migration"

✓ Manual checkpoint created
  Name: Before database migration
  Files: 0 (pre-change snapshot)
  Time: 2025-10-25 14:30:00

User: "Proceed with migration"

Claude: *performs migration*

# If issues occur:
/rewind

[Checkpoints]
1. [Manual] Before database migration
2. [Auto] Previous changes...

Select: 1 (Manual checkpoint)
✓ Restored to pre-migration state

Preview Changes Before Rewind

/checkpoint-manager --preview

[Checkpoint Preview]
Restoring to: [5 min ago] Implemented caching layer

Files to be reverted:
  src/services/cache.service.ts
    - 45 lines added will be removed
    - 12 lines modified will be restored

  src/config/redis.config.ts
    - File will be deleted (was created in this session)

  tests/cache.service.test.ts
    - File will be deleted (was created in this session)

Conversation:
  - Last 8 messages will be removed
  - Rewind to: "Let's add a caching layer"

Proceed with rewind? (y/n): y

✓ Checkpoint restored

List All Checkpoints

/checkpoint-manager --list

[Session Checkpoints]

📍 Manual Checkpoints:
1. Before database migration (14:30:00)
   Files: Initial state preserved

⚡ Auto Checkpoints:
2. Implemented user authentication (14:25:12)
   Files: auth.service.ts, user.model.ts, routes/auth.ts

3. Fixed login validation (14:20:45)
   Files: auth.service.ts

4. Created auth endpoint (14:15:33)
   Files: routes/auth.ts

5. Added password hashing (14:10:22)
   Files: auth.service.ts, user.model.ts

Total: 5 checkpoints (1 manual, 4 auto)
Session duration: 25 minutes

Checkpoint Limitations

What Checkpoints DO Track

✅ File edits made by Claude Code tools (edit_file, write_file) ✅ File content at time of snapshot ✅ Conversation history and context ✅ File metadata (permissions, timestamps)

What Checkpoints DON'T Track

❌ Bash command side effects (files created by shell commands) ❌ Manual edits made outside Claude Code ❌ git operations (commits, pushes, merges) ❌ Database changes ❌ External API calls

Example: Bash Limitations

User: "Create a backup directory"

Claude: *runs bash command*
$ mkdir backup && cp -r src backup/

✓ Directory created

# Later, rewind checkpoint
/rewind

⚠️  Warning: Checkpoint cannot revert bash command side effects
    The 'backup' directory will remain
    You may need to manually clean up:
    $ rm -rf backup

Integration with Git

Checkpoints vs Git Commits

Checkpoints:

• Session-level (temporary)
• Automatic, no manual intervention
• Fast rewind (instant)
• Lost after session ends

Git Commits:

• Permanent version control
• Manual commit process
• Can share with team
• Persistent across sessions

Recommended Workflow

1. Checkpoints for exploration:
   - Try risky changes
   - Rewind if doesn't work
   - Iterate until satisfied

2. Git commits for milestones:
   - Commit when checkpoint result is good
   - Permanent record
   - Share with team

Example: Checkpoint + Git Workflow

User: "Try refactoring the auth system"

Claude: *refactors*

[Auto Checkpoint: Before auth refactor]

User: *tests*
User: "Works great! Commit this"

/git-smart-commit "Refactor auth system for better separation of concerns"

✓ Committed to git
✓ Checkpoint becomes permanent

Advanced Patterns

Exploratory Coding Pattern

1. Manual checkpoint before exploration
   /checkpoint-manager --create "Before experiment"

2. Try Approach A
   - Implement
   - Test
   - Not ideal? Rewind

3. Try Approach B
   - Implement
   - Test
   - Better? Keep it

4. Commit successful approach
   git commit -m "Implemented approach B"

Refactoring Safety Net

# Before large refactor:
/checkpoint-manager --create "Before refactor: Working state"

# Refactor incrementally:
1. Refactor module A
2. Test
3. If broken, rewind
4. If working, continue
5. Refactor module B
6. Repeat

# Final: Commit all changes
git commit -m "Refactored modules A-E"

Debugging with Checkpoints

User: "The app broke, not sure when"

/checkpoint-manager --list

[Checkpoints]
1. [5 min ago] Added caching
2. [10 min ago] Optimized queries
3. [15 min ago] Updated dependencies
4. [20 min ago] Fixed validation

# Binary search for breaking change:
Restore to checkpoint 2
  → Still broken
Restore to checkpoint 3
  → Works!

Conclusion: "Optimized queries" (checkpoint 2) broke the app

# Fix the query optimization:
User: "The query optimization broke it. Let's fix that specific change"

Configuration

Auto-Checkpoint Settings

// .claude/checkpoint.config.json
{
  "autoCheckpoint": {
    "enabled": true,
    "interval": 1, // Every N file edits
    "maxCheckpoints": 50, // Keep last 50 checkpoints
    "includeTests": false // Don't checkpoint test file changes
  },
  "rewindDefaults": {
    "restoreMode": "both", // code-only, conversation-only, both
    "confirmBeforeRestore": true,
    "showPreview": true
  }
}

Disable Auto-Checkpoints

/checkpoint-manager --disable-auto

⚠️  Auto-checkpoints disabled
    You can still create manual checkpoints with:
    /checkpoint-manager --create "checkpoint name"

Custom Checkpoint Intervals

/checkpoint-manager --interval=5

✓ Auto-checkpoints will be created every 5 file edits

Best Practices

1. Create Manual Checkpoints Before Risk

   • Database migrations
   • Large refactors
   • Experimental approaches

2. Use Code-Only Restore for Discussion Preservation

   • Valuable context in conversation
   • Only code needs reverting

3. Preview Before Rewind

   • Verify what will be reverted
   • Avoid accidental loss of good changes

4. Commit Good Checkpoints to Git

   • Checkpoints are temporary (session-only)
   • Git commits are permanent

5. Don't Rely on Checkpoints for Bash Commands

   • Checkpoints don't track shell side effects
   • Use git for permanent backups

6. Regular Manual Checkpoints for Long Sessions

   • Every 30-60 minutes
   • Before context switches

7. Clean Up After Bash Reverts

   • Manually remove directories/files created by shell
   • Checkpoints will warn about bash limitations

Troubleshooting

"No checkpoints available"

Cause: Session just started, no changes made yet
Solution: Make some changes first, checkpoints auto-create

"Cannot rewind bash command changes"

Cause: Bash commands create files outside checkpoint tracking
Solution: Manually clean up with reverse commands
  Created directory: rm -rf directory
  Modified external files: restore from git

"Checkpoint restored but issue persists"

Cause: Issue may be in database, environment, or external state
Solution: Check non-code factors:
  - Database state
  - Environment variables
  - External service configuration

"Lost conversation context after rewind"

Cause: Restored "both" which includes conversation
Solution: Use "code-only" restore to preserve discussion
  /rewind → Select checkpoint → [R] Code Only