Devops Monk

When Claude Code works on your project, it can touch dozens of files in a single prompt—refactoring a module, renaming methods across the codebase, restructuring folders. What happens when it goes wrong? Traditional developers rely on keyboard undo or Git commits, but neither fits an AI that operates at speed.

Claude Code’s checkpoints are your safety net. They automatically capture the state of your code before each edit, letting you rewind in seconds if anything goes sideways.

What Are Checkpoints?

Checkpoints are automatic snapshots of your code state captured silently before Claude touches anything.

Key facts:

• Persist across sessions (close your terminal, they’re still there)
• Don’t disappear when you close Claude Code
• Expire after 30 days
• Only track direct file edits made through Claude’s editing tools
• Do NOT track changes made by bash commands (rm file.txt, mv old.txt new.txt, cp source dest)

Why Checkpoints Matter

Before Claude Code, developers had to choose between:

1. Keyboard Undo — Works fine for single-file edits, but when Claude updates 5 files simultaneously:

   • Which file changed first?
   • How many times do you undo?
   • Did you accidentally remove something important?
   • Undo becomes guesswork.

2. Git Commits — Powerful but not designed for constant experimentation. Creating a safe point requires:

   • git add .
   • Write a commit message
   • Run git commit
   • Result: messy commits like “test”, “in-progress”, “ignore” cluttering history.

3. Manual Backups — Copying folders or making ZIPs:

   • Takes time
   • Breaks your concentration
   • Most people forget to do it
   • By the time something breaks, there’s no recent backup.

Checkpoints solve all three problems.

How Checkpoints Work

Every prompt you submit triggers a silent snapshot before Claude touches anything. No save button. No planning. Just automatic protection.

You: "Refactor the auth module"
↓
[Checkpoint created automatically]
↓
Claude modifies files

If Claude’s changes go sideways, you can rewind in seconds.

Checkpoints also persist across sessions, so you can close your terminal and still rewind later.

When Checkpoints Are Essential

Scenario 1: Exploring Risky Approaches

You want Claude to try a completely different architectural pattern, but you’re not 100% sure it’ll work.

Checkpoint gives you safety to experiment without fear.

Scenario 2: Claude Misunderstands the Prompt

You asked for a small refactor and Claude rewrote three modules. Before you even figure out what changed, checkpoint lets you rewind in seconds.

You: "Simplify the login form component"
Claude: *accidentally refactors entire auth flow*
You: Press Esc twice → /rewind → Select checkpoint → Done

Scenario 3: Context Gets Polluted

You’ve corrected Claude twice on the same issue and it keeps making the same mistake.

Rewind to before the first wrong attempt and try again with a better prompt—a clean prompt almost always outperforms a long session with accumulated corrections.

Scenario 4: Direction Changes Mid-Session

You were migrating to version 4 across multiple prompts, then requirements changed to use version 5.

Rewind both code and conversation to the pre-migration state and start fresh—without losing any work outside that scope.

How to Rewind

Press Esc twice or use:

/rewind

This opens the rewind menu. Pick a checkpoint and decide what to restore:

Restore Code Only

• Reverts file changes, keeps the conversation
• Good when: The code went wrong but the context is still useful

Restore Conversation Only

• Rewinds the chat, keeps the code
• Good when: You want to re-prompt differently without throwing away changes you liked

Restore Both

• Full reset — code and conversation go back together
• Good when: Everything needs a reset

Summarize from Here

• Doesn’t restore anything
• Instead, condenses messages from that point forward while keeping earlier context intact
• A surgical alternative to /compact that only compresses the part eating up space

Critical Limitation: What Checkpoints DON’T Track

This is crucial: Checkpointing does NOT track files modified by bash commands.

If Claude runs:

rm file.txt
mv old.txt new.txt
cp source.txt dest.txt

These modifications cannot be undone through rewind. Only direct file edits made through Claude’s file editing tools are tracked.

Workaround: If you need to protect files from bash modification, use hooks (see Hooks guide) to prevent dangerous commands or use Git commits before risky operations.

Checkpoints vs Git: Complementary, Not Competitive

Think of them this way:

• Checkpoints = local undo (frictionless, session-scoped, 30-day lifespan)
• Git = permanent history (travels with your repo, team-shareable, CI/CD traceable)

They work together, not against each other.

Before a Large Task: Commit Your Working State

git checkout -b feature/refactor-auth
git add .
git commit -m "before AI refactor"

If everything breaks, git reset --hard brings you back instantly. Unlike checkpoints, this:

• Survives beyond 30 days
• Travels with your repo
• Works in team environments
• Provides permanent history

Best Practices

Common Mistakes

Mistake: Relying on checkpoints for everything Fix: Use Git for large tasks, checkpoints for experimentation

Mistake: Thinking checkpoints track bash commands Fix: Remember—only direct Claude file edits are tracked

Mistake: Assuming checkpoints last forever Fix: They expire after 30 days; use Git for permanent history

Next Steps

• Session Management Guide: Learn how to organize long sessions effectively
• Hooks Guide: Automate actions before/after Claude’s work
• Git Integration Guide: Use Git alongside Claude Code for powerful workflows