Claude Code: Checkpoints and Rollback
Last updated: 2026-08-31
Checkpoints are Claude Code's safety net — auto-snapshots before critical operations, rollback anytime if problems arise.
💡 Tip: Checkpoints aren't just git commits — they're session-granularity snapshots recording each operation's state for precise rollback to any step.
📋 Prerequisites: Chapter 19 - CLI Reference Manual
1. What You'll Learn
- Checkpoint mechanism and auto-snapshots
- Manual checkpoint creation
- Rollback to any step
- Checkpoint vs git relationship
- Safety net strategies
2. Checkpoint Mechanism
(1) How It Works
| Trigger Condition | Auto-Create | Description |
|---|---|---|
| Session start | ✅ | Records initial state |
| Before file modification | ✅ | Records pre-modification state |
| Before command execution | ✅ | Records pre-command state |
| Manual request | ✅ | /checkpoint |
▶ Example 1: View Checkpoint List
TEXT
📖 Display only
> /checkpoints
#1 [14:20:00] Session start | 0 files changed
#2 [14:22:15] Modified jwt.ts | 2 files changed
#3 [14:25:30] Modified auth.ts | 1 file changed
#4 [14:30:15] Added tests | 3 files changed
#5 [14:35:00] Current state | 6 files changed
3. Manual Checkpoints
(1) Create Checkpoint
TEXT
📖 Display only
> /checkpoint
✅ Checkpoint #6 created
> /checkpoint "Pre-migration state"
✅ Checkpoint #6 created with description
(2) Best Practices — When to Create
| Timing | Reason |
|---|---|
| Before major changes | Refactoring, migration, etc. |
| Milestone completion | A feature point finished |
| Uncertain operations | Before experimental modifications |
| Before leaving | Save current progress |
▶ Example 2: Before Major Changes
TEXT
📖 Display only
> /checkpoint "Pre-migration state"
✅ Checkpoint #6 created
> Migrate auth from Session to JWT
Claude Code: Modifying 12 files... 3 tests failed ❌
# Alice decides to rollback and try differently
> /rollback 6
✅ Rolled back to checkpoint #6 (pre-migration state)
4. Rollback Operations
(1) Rollback Methods
| Command | Description |
|---|---|
/rollback |
Rollback to previous checkpoint |
/rollback <n> |
Rollback to specified checkpoint |
/undo |
Undo most recent operation |
git checkout . |
Revert all uncommitted changes |
▶ Example 3: Step-by-Step Rollback
TEXT
📖 Display only
> /checkpoints
#1 [14:20] Start
#2 [14:22] Added UserService
#3 [14:25] Added tests
#4 [14:30] Refactored UserService (failed)
#5 [14:35] Attempted fix (still failing)
# Only rollback failed refactoring, keep successful additions
> /rollback 3
✅ Rolled back to checkpoint #3
Kept: UserService + tests
Reverted: Refactor + fix attempt
# Refactor with different approach
> Refactor UserService with different approach
5. Checkpoints vs Git
(1) Comparison
| Dimension | Checkpoint | Git |
|---|---|---|
| Granularity | Operation-level | Commit-level |
| Persistence | Session-only | Permanent |
| Storage | Memory/temp | Repository |
| Sharing | Not shareable | Pushable |
| Rollback | Precise to step | Precise to commit |
(2) Cooperative Strategy
TEXT
📖 Display only
# Best practice: Checkpoint + git double insurance
# 1. Git commit before session
git add -A && git commit -m "before: claude session"
# 2. Use checkpoints for in-session rollback
/checkpoint "Milestone complete"
/rollback 3
# 3. Git commit after session
git add -A && git commit -m "feat: user auth module"
# 4. If entire session fails, git rollback
git reset --hard HEAD~1
6. Multi-Layer Safety Net
TEXT
📖 Display only
Level 1: /undo — Undo most recent operation
Level 2: /rollback — Rollback to checkpoint
Level 3: git checkout — Revert uncommitted changes
Level 4: git reset — Rollback to any commit
Level 5: git reflog — Recover lost commits
❓ FAQ
Q How long are checkpoints retained?
A Only within the current session. Exits lose checkpoints, but git commits are permanent.
Q Does rollback lose all progress?
A No. Rollback to a specific checkpoint only reverts changes after that point; earlier changes are preserved.
Q Can I rollback a single file?
A Checkpoint rollback is per-step. Single file rollback:
git checkout -- <file>.Q After rollback, does Claude Code remember previous conversation?
A Yes. Conversation history is preserved but file state is rolled back. Claude Code knows what you did and what you rolled back.
📖 Summary
- Checkpoints auto-create before critical operations; manual via
/checkpoint /rollback <n>for precise rollback to specified step- Checkpoints are session-level; git is permanent; use both together
- Multi-layer safety net: undo → rollback → git checkout → git reset → reflog
- Always create checkpoints before major changes
📝 Exercises
- Basic (⭐): Create checkpoint, make changes, rollback, verify file restored.
- Intermediate (⭐⭐): Execute 3 modification steps, rollback to step 2, verify step 1 preserved and step 3 reverted.
- Advanced (⭐⭐⭐): Design multi-layer safety net combining checkpoints and git for any-operation recovery.
