Checkpointing - Safe Rollback for Agent Work

Agents make mistakes. They delete files, overwrite code, or head down wrong paths. Checkpointing is your safety net—automatic snapshots that let you roll back when things go sideways.

What Are Checkpoints?

Checkpoints are point-in-time snapshots of your project state. Claude Code creates them automatically before making changes, giving you a restore point if needed.

Two types of checkpoints:

• Git checkpoints - Snapshots of file changes (commits on a shadow branch)
• Conversation checkpoints - Session state including context and decisions

Think of it like autosave in a video game. You can always reload from the last checkpoint.

How Checkpoints Work

Claude Code creates checkpoints automatically:

1. Before any file modification
2. Before running potentially destructive commands
3. At regular intervals during long sessions

Checkpoints are stored as git commits on a dedicated branch, separate from your working branch. Your commit history stays clean.

main (your branch)
│
├── checkpoint-1 (before edit)
├── checkpoint-2 (before delete)
└── checkpoint-3 (before refactor)

No action required on your part. Checkpoints happen in the background.

Viewing Checkpoints

List available checkpoints:

/checkpoints

Output shows timestamp, description, and what changed:

[1] 2024-01-15 14:32 - Before editing config.toml
[2] 2024-01-15 14:28 - Before deleting old tests
[3] 2024-01-15 14:15 - Session start

Restoring From a Checkpoint

Roll back to a previous state:

/restore 1

This reverts all file changes made after checkpoint 1. Your conversation context is preserved—the agent remembers what happened, even after rollback.

For conversation state rollback:

/restore 1 --full

This restores both files and conversation state. Useful when the agent went down a completely wrong path.

When to Use Checkpoints

Restore when:

• Agent deleted something important
• Refactoring made things worse
• You want to try a different approach
• Tests broke after changes

Don’t restore when:

• You can fix the issue manually faster
• Only minor changes need reverting (use git directly)
• You want to keep some changes (cherry-pick instead)

Best Practices

Check before long operations. Before asking the agent to refactor an entire codebase, verify a checkpoint exists:

/checkpoints

Name your restore points. Create explicit checkpoints before risky work:

/checkpoint "before migration"

Review diffs before restoring. See what you’ll lose:

/diff 1

Commit good states. Once work is solid, commit to your actual branch. Checkpoints are temporary—they get cleaned up.

Limitations

• Checkpoints don’t track untracked files (git limitation)
• Large binary files may not checkpoint efficiently
• External state (databases, APIs) cannot be rolled back
• Old checkpoints are pruned after ~24 hours

The Safety Mindset

Checkpoints enable confident experimentation. When you know you can always roll back, you’re free to:

• Let agents try ambitious refactors
• Experiment with different approaches
• Recover from “oops” moments without panic

The best autonomous workflows have multiple safety layers. Checkpointing is one. Code review is another. Tests are a third. Stack them.

Next: Working with Git - How agents handle version control