How to Rollback Changes in Claude Code: Quick Guide to Checkpoints & Rewind

TL;DR - Rollback in 30 Seconds

# View your checkpoints
/checkpoint list

# Rollback to previous checkpoint
/rewind 1

# Rollback multiple checkpoints
/rewind 3

# Create manual checkpoint before risky changes
/checkpoint create "Before major refactor"

# That's it! Your code is restored.

Key Concept: Claude Code automatically creates checkpoints before major changes. You can instantly rewind to any checkpoint without git knowledge.

---

What is a Checkpoint?

A checkpoint is a snapshot of your codebase at a specific moment in time. Think of it as a save point in a video game - you can always go back if things go wrong.

How Checkpoints Work

Your Coding Timeline:
──────────────────────────────────────────────────
Time:   10:00        10:15         10:30
Action: Fix bug  →  Add feature → Refactor

Checkpoints created automatically:
[CP1]            [CP2]           [CP3]
"Before          "Before         "Before
bug fix"         new feature"    refactor"

If refactor breaks something:
/rewind 1 → Back to 10:15 (before refactor)
/rewind 2 → Back to 10:00 (before feature)

Automatic vs Manual Checkpoints

Automatic (Claude creates these):

• Before editing multiple files
• Before major refactoring
• Before running risky operations
• Before migrations or deletions

Manual (You create these):

/checkpoint create "Your description here"

---

Step-by-Step: Rollback Guide

Step 1: View Available Checkpoints

# In your Claude Code session
/checkpoint list

# Output:
┌───┬──────────────────────────────────┬─────────────┐
│ # │ Description                      │ Time        │
├───┼──────────────────────────────────┼─────────────┤
│ 3 │ Before database migration        │ 10:45 AM    │
│ 2 │ After adding tests               │ 10:30 AM    │
│ 1 │ Before refactoring auth module   │ 10:15 AM    │
│ 0 │ Initial state                    │ 10:00 AM    │
└───┴──────────────────────────────────┴─────────────┘

Current: Checkpoint 3

Reading the list:

• #3 = Most recent (current state)
• #0 = Oldest checkpoint
• You're currently at #3

---

Step 2: Rewind to a Previous Checkpoint

# Rollback 1 checkpoint (back to #2)
/rewind 1

# Output:
✓ Rewound to checkpoint: "After adding tests"
✓ Restored 5 files
✓ Current state: Checkpoint 2

Files restored:
  - src/database/migrate.js (deleted)
  - src/models/User.js (reverted to previous version)
  - tests/user.test.js (reverted)

What happened:

• All files changed between checkpoint 2 and 3 are reverted
• Your codebase is exactly as it was at 10:30 AM
• Checkpoint 3 still exists (you can go forward)

---

Step 3: Go Forward Again (If Needed)

# Changed your mind? Go back to checkpoint 3
/rewind -1

# Or use explicit checkpoint number
/checkpoint restore 3

# Output:
✓ Restored to checkpoint: "Before database migration"
✓ Current state: Checkpoint 3

---

Common Rollback Scenarios

Scenario 1: Refactor Broke Tests

Problem: You refactored code, but tests now fail.

# You're here (tests failing):
> "Run the tests"

 FAIL  tests/auth.test.js
   ✕ Login should work (89ms)

# Rollback to before refactor
/rewind 1

# Output:
✓ Rewound to: "Before auth refactor"
✓ All files restored

# Tests now pass again!
> "Run the tests"

 PASS  tests/auth.test.js

Next Steps:

1. Analyze what broke
2. Describe the issue to Claude
3. Let Claude fix the refactor
4. Create new checkpoint: /checkpoint create "Fixed refactor"

---

Scenario 2: Accidental File Deletion

Problem: Claude deleted important files you needed.

# Claude just deleted config files
✓ Deleted: config/database.js
✓ Deleted: config/redis.js

# Panic! You needed those!

# Rollback immediately
/rewind 1

# Output:
✓ Restored: config/database.js
✓ Restored: config/redis.js

---

Scenario 3: Trying Experimental Changes

Problem: You want to experiment but preserve current working state.

# Create checkpoint before experimenting
/checkpoint create "Before experimental GraphQL refactor"

# Now ask Claude to try something risky
> "Refactor the entire API to use GraphQL instead of REST"

# Claude makes major changes...

# Review the changes
/list

# If you don't like it:
/rewind 1

# If you like it:
/checkpoint create "GraphQL migration successful"

---

Scenario 4: Multiple Checkpoints Back

Problem: You made several changes and want to go back to the beginning.

# View timeline
/checkpoint list

│ 5 │ After styling updates            │ 11:30 AM    │
│ 4 │ After adding analytics           │ 11:15 AM    │
│ 3 │ After refactoring components     │ 11:00 AM    │
│ 2 │ After adding tests               │ 10:45 AM    │
│ 1 │ Initial working version          │ 10:30 AM    │

# Go back to "Initial working version" (4 checkpoints back)
/rewind 4

# Output:
✓ Rewound to: "Initial working version"
✓ Restored 18 files
✓ Undone: styling, analytics, refactor, tests

---

Advanced Rollback Techniques

Selective File Restoration

Can't restore just one file from a checkpoint? Here's the workaround:

# Option 1: Rewind, save file, go forward
/rewind 2                        # Go back to checkpoint with the file
# Copy the file content manually
/rewind -2                       # Return to current

# Option 2: Use git (if you've committed)
> "Use git to restore src/config.js from 2 commits ago"
# Claude executes: git checkout HEAD~2 -- src/config.js

# Option 3: Ask Claude
> "I need the version of config.js from checkpoint 2,
>  but keep everything else from checkpoint 5"
# Claude will manually retrieve and apply it

---

Creating Strategic Checkpoints

When to manually create checkpoints:

# ✅ DO create checkpoints before:
/checkpoint create "Before database migration"
/checkpoint create "Before switching to TypeScript"
/checkpoint create "Before major API refactor"
/checkpoint create "Working version before optimization"

# ❌ DON'T create checkpoints for:
# - Small changes (automatic checkpoints handle this)
# - Every single edit (clutters checkpoint list)
# - After breaking code (checkpoints should be stable states)

Best Practice Pattern:

1. Reach stable state (tests pass, code works)
2. Create checkpoint: "Stable - [description]"
3. Make risky changes
4. Test
5a. If success → Create new checkpoint
5b. If failure → /rewind 1

---

Checkpoint Naming Tips

Good checkpoint names:

✅ /checkpoint create "Before migrating to Prisma"
✅ /checkpoint create "Working auth system - tests passing"
✅ /checkpoint create "After adding Redis caching - benchmark 50ms"
✅ /checkpoint create "Stable v1.2 - ready for deployment"

Bad checkpoint names:

❌ /checkpoint create "Stuff"
❌ /checkpoint create "Checkpoint 1"
❌ /checkpoint create "asdfasdf"
❌ /checkpoint create "Changes"

Good names help you identify the right checkpoint to restore later.

---

Checkpoints vs Git: What's the Difference?

Feature	Claude Code Checkpoints	Git
Setup	Automatic (built-in)	Manual (must run commands)
Frequency	Every major change	Whenever you commit
Speed	Instant (/rewind 1)	Slower (git reset, git revert)
Granularity	Fine-grained (every AI action)	Coarse (only when you commit)
Knowledge Required	None (simple commands)	Moderate (git concepts)
Persistence	Session-based (lost when session ends)	Permanent (survives restarts)
Sharing	Not shareable	Push to remote (team access)

Best Practice: Use both!

# Workflow:
1. Use checkpoints for rapid iteration in Claude Code session
2. When you reach a stable state, commit with git:
   > "Create a git commit with these changes"
3. Continue using checkpoints for next iteration
4. Commit again when stable

# Checkpoints = short-term safety net
# Git commits = long-term version control

---

Troubleshooting Rollback Issues

Problem: "No checkpoints available"

/rewind 1

# Error: No previous checkpoints found

# Causes:
1. You just started the session (no checkpoints created yet)
2. You cleared context (/clear)
3. Session was restarted

# Solution:
# Start making changes - Claude will create checkpoints automatically
# Or create manual checkpoint: /checkpoint create "Initial state"

---

Problem: "Checkpoint not found"

/rewind 10

# Error: Only 3 checkpoints available

# Solution:
# Check available checkpoints first
/checkpoint list

# Then rewind to valid checkpoint
/rewind 3

---

Problem: "Files modified outside Claude Code"

/rewind 1

# Warning: These files were modified externally:
#   - src/app.js (edited in IDE)
#   - package.json (npm install changed this)
# Rewind may cause conflicts.

# Options:
1. Proceed anyway (may lose external changes)
2. Cancel and manually merge
3. Create checkpoint first, then rewind

# Recommendation:
# Don't edit files in IDE while Claude Code is running
# Or save IDE changes before rewinding

---

Quick Reference Card

Essential Commands

# View checkpoints
/checkpoint list

# Create manual checkpoint
/checkpoint create "Description"

# Rollback
/rewind 1              # Back 1 checkpoint
/rewind 3              # Back 3 checkpoints
/rewind -1             # Forward 1 checkpoint

# Restore specific checkpoint
/checkpoint restore 2  # Go to checkpoint #2

# Clear all checkpoints (careful!)
/clear                 # Clears context AND checkpoints

Keyboard Shortcuts

(No built-in shortcuts, but you can create aliases)

# Add to ~/.bashrc or ~/.zshrc:
alias cpl='/checkpoint list'
alias cpc='/checkpoint create'
alias rw1='/rewind 1'
alias rw2='/rewind 2'

# Then use:
cpl        # List checkpoints
cpc "msg"  # Create checkpoint
rw1        # Rewind 1

---

Best Practices Summary

✅ DO:

1. Create checkpoints before major changes

   /checkpoint create "Before risky refactor"
   

2. Review changes before creating checkpoints

   /list                    # See what changed
   /checkpoint create "..."  # Then save
   

3. Use descriptive names

   /checkpoint create "Auth working - tests pass - 10:30 AM"
   

4. Combine with git for long-term safety

   > "Commit these changes with git"
   

5. Rewind fearlessly - checkpoints are non-destructive

   /rewind 1   # You can always go forward again
   

---

❌ DON'T:

1. Don't rely on checkpoints after session ends

   • Checkpoints are session-based
   • Use git commits for permanent history

2. Don't edit files externally during session

   • Can cause conflicts with rewind
   • Pause Claude Code, edit, resume

3. Don't create too many manual checkpoints

   • Automatic checkpoints usually sufficient
   • Manual checkpoints for strategic points only

4. Don't forget checkpoints expire with session

   /exit  # Closes session
   # Checkpoints are lost!
   # Commit with git first if needed
   

---

Real-World Example: Safe Refactoring Workflow

# Day: Friday afternoon, risky refactor ahead

# 1. Start session
claude

# 2. Create checkpoint at stable state
/checkpoint create "Stable - all tests passing - ready for refactor"

# 3. Request refactor
> "Refactor the authentication system to use JWT instead of sessions"

# Claude creates automatic checkpoint before changes
[Checkpoint: "Before auth refactor"]

# Claude makes changes...

# 4. Review changes
/list

# 5. Test
> "Run all tests"

# 6a. Tests pass? Create checkpoint!
/checkpoint create "JWT auth complete - tests passing"

# 6b. Tests fail? Rollback!
/rewind 1

# Try again with more context
> "The tests failed because of session middleware.
>  Please remove session middleware and use JWT middleware instead."

# Iterate until successful

# 7. When stable, commit with git
> "Create git commit: 'feat: migrate auth to JWT'"

# 8. Continue working
# Checkpoints continue protecting you...

---

Next Steps

Now that you've mastered rollback, explore more Claude Code features:

1. Learn Subagents: Parallel Development with Subagents
2. Master Checkpoints: Complete Checkpoint System Guide
3. Best Practices: Claude Code Best Practices
4. Getting Started: Complete Setup Guide

---

Quick FAQ

Q: How many checkpoints can I create? A: No hard limit, but keep it reasonable. Claude Code stores checkpoints in memory during the session.

Q: Do checkpoints survive restart? A: No. Checkpoints are session-based. Use git commits for permanent history.

Q: Can I share checkpoints with team? A: No. Use git for team collaboration. Checkpoints are local to your session.

Q: Do checkpoints include dependencies (node_modules)? A: No. Checkpoints only track source files, not dependencies. Re-run npm install if needed after rewind.

Q: Can I rewind if I've exited Claude Code? A: No. Checkpoints are lost when you exit. Always commit important changes to git before exiting.

Q: What if I rewind too far? A: No problem! Use /rewind -1 to go forward, or /checkpoint restore N to jump to a specific checkpoint.

---

Conclusion

Rollback in Claude Code is simple and powerful:

1. Automatic checkpoints protect you by default
2. /rewind N instantly restores previous state
3. Manual checkpoints let you mark strategic points
4. Non-destructive - you can always go forward again

Code fearlessly with the safety net of instant rollback! 🚀

---

Quick Command Card (bookmark this!):

/checkpoint list              # See all checkpoints
/checkpoint create "msg"      # Save current state
/rewind 1                     # Undo last change
/rewind 3                     # Undo last 3 changes
/checkpoint restore 2         # Jump to checkpoint #2

Happy (safe) coding! 🛡️