D6 · Checkpoints, rewind and session management

Claude Code gives you two safety nets: in-session checkpoints (files are automatically snapshotted before every prompt, /rewind anytime) and cross-session management commands (continue, resume, branch, compact). Master both layers and you can hand big tasks over with confidence — because every step can be undone, and every day can be resumed.

Why this lesson comes today

D2 covered how the context window fills up and why compaction is the survival tool; D5 covered planning before acting. But even with a good plan, long tasks drift mid-flight: you break something and want to take it back, want to retry down a different path, need to slim down a tight context, or can't finish today and must continue tomorrow. All of these "undo and keep-alive" abilities live in this lesson.

It also lays groundwork for later: D10 Subagents will run into one of this lesson's limits again (subagent edits don't enter checkpoints), and the parallel sessions of D11 Worktrees are built entirely on being fluent with a single session. Skip this lesson, and every future mishap leaves you firefighting with manual git checkout.

Core concepts, explained

Checkpoints: an automatic snapshot before every prompt

OfficialEvery time you send a prompt, Claude Code automatically creates a checkpoint before executing, recording the current code state; every change Claude makes with its own file-editing tools is tracked. Only the most recent 100 checkpoints in a session are kept; checkpoints are saved along with the session, so you can still /rewind after resuming an old session; sessions (checkpoints included) are deleted after 30 days by default, adjustable with the cleanupPeriodDays setting.

Our takeThe key to understanding it is "two tracks": one is conversation history (what you and Claude have said), the other is file state (the code on disk). A checkpoint "pins" the two tracks together at each prompt; when rewinding you can roll back just one track, or both together:

The rewind menu: three restores + two summarizes

OfficialRun /rewind, or press Esc twice while the input box is empty, to open the rewind menu (with text in the input box, double-Esc clears the input instead; the cleared text goes into input history — press ↑ to get it back). The menu lists every prompt you've sent this session; select a point and you get six actions:

• Restore code and conversation: code and dialogue both return to that point;
• Restore conversation: roll back only the dialogue, keeping the current code;
• Restore code: roll back only the files, keeping the dialogue;
• Summarize from here: compress the conversation after that point into a summary, freeing context space;
• Summarize up to here: compress the conversation before that point into a summary, keeping later messages;
• Never mind: do nothing, back to the list.

OfficialThe two code-restore options only appear when there actually are tracked file changes after the selected checkpoint. After rewinding the conversation or choosing Summarize from here, the original text of that prompt is refilled into the input box so you can tweak it and resend. Summarizing doesn't change files on disk, and the original messages still remain in the session transcript; while a Summarize option is selected, you can type guidance under "add context (optional)" to steer what the summary keeps. Officially, summarize is positioned as "a targeted /compact" — staying in the same session to shrink context; to strike out and try a new approach, use /branch instead (below).

OfficialThere's also a hidden entry: if /clear has run in this Claude Code process, the top of the rewind menu gains a /resume <session-id> (previous session) row — pick it to return to the session as it was before /clear (requires v2.1.191+).

Clearing up a misconception: checkpoints are not git

Our takeThe common misreading is "with rewind I don't need git anymore". In reality, checkpoints cover exactly one class of change: edits Claude made in this session with its file-editing tools. The four classes below are all beyond its reach — the test is to ask "was this change made by Claude, in this session, with an editing tool?":

• OfficialBash-command changes aren't tracked: file changes caused by Claude running rm file.txt, mv old.txt new.txt, cp source.txt dest.txt can't be undone by rewind;
• OfficialSubagent edits don't roll back: apart from context: fork skills running in the foreground, subagent edits land outside your session's checkpoints — use git to undo them;
• OfficialOut-of-session changes aren't tracked: files you edited by hand, or that other parallel sessions edited, are generally not captured;
• OfficialSymlink/hardlink paths don't restore: these paths are skipped during a restore with the notice Restored the code, but skipped N files (warning added in v2.1.216).

OfficialThe official positioning: checkpoints are "local undo", git is "permanent history" — the former complements rather than replaces the latter. Our takeA practical division of labor: before a big change, git commit a clean baseline first; while working, use rewind for quick take-backs; once you're happy with the result, let git make it permanent. For how to choose between them and which scenarios each one backstops, see Tip: Botched a change — roll back with checkpoint or git?.

Session lifecycle: continue, resume, fork, compact

OfficialA session is a saved conversation bound to a project directory, continuously written to a local transcript file as you chat (by default ~/.claude/projects/<project>/<session-id>.jsonl). So quitting, a power cut, or /clear loses nothing:

OfficialA resumed session brings back: the full conversation history (tool calls included), the model in use, the agent identity, and the permission mode (though plan and bypassPermissions are never restored — the latter must be explicitly re-enabled at startup). Note that some startup configuration does not come back: flags like --mcp-config, --settings, --plugin-dir, --add-dir must be passed again when resuming; configuration living in settings.json is re-read on every startup and unaffected.

Official/branch prints two session IDs (the new branch and the original); the original stays in the picker, ready to return to anytime. Because the branch runs in the same process, permissions granted "for this session" remain valid, and in-flight background subagents and background bash keep running with their output flowing into the new branch; forking a separate process with --fork-session means granting permissions again.

Long tasks without losing context: the three moves

Our takeString this lesson's tools into one working method, matched to three typical situations:

• Went off course → /rewind, choose "Restore code and conversation" back to the prompt before things broke, and use the refilled original text to rewrite the ask and resend;
• Context is tight but the task isn't done (D2's old problem) → use "Summarize from here" to spot-compress the long-winded debugging stretch while keeping the task brief at the top; or just /compact [focus instructions] — run /context first to see what's actually eating the space;
• Want to try a second approach in parallel → /branch try-b; if it fails, /resume back to the mainline — neither side contaminates the other.

OfficialWhen you resume a long session the next day (Pro/Max plans, idle roughly an hour or more and over 100,000 tokens), Claude Code first shows a dialog: "Resume from summary" compresses it into a summary on the spot before continuing (each later request is cheaper, but detail is lossy), "Resume full session as-is" loads everything (full detail, every request billed on the full history), "Don't ask me again" stops asking. This is exactly D2's cost-versus-detail trade-off replayed at session-resume time.

Hands-on: doable today

Grab a test repo (or mkdir cc-d6-lab && cd cc-d6-lab && git init), about 25 minutes end to end:

1. Create two checkpoints: start claude; with the first prompt, have it create hello.py printing a fixed message; with the second, have it switch to reading the name from a command-line argument. Expected: both rounds of edits complete.
2. Open the rewind menu: clear the input box and press Esc twice (or type /rewind). Expected: a list of the two prompts you sent.
3. Restore code only: select the second prompt and choose "Restore code". Expected: hello.py returns to version one while the conversation log stays intact — the "two tracks roll back separately" idea made tangible.
4. Verify the blind spot: paste the prompt below; once it finishes, rewind again and choose "Restore code". Expected: tracked.txt is undone and disappears, untracked.txt stays put — bash changes don't enter checkpoints; seeing is believing:

Run a checkpoint-boundary experiment, in two separate steps:
1. Use your file-editing tool (not bash) to create tracked.txt containing the single line "created by edit tool".
2. Use bash's echo command to create untracked.txt containing the single line "created by bash".
When done, tell me which method created each of the two files. Make no other changes.

5. Name and resume: run /rename d6-lab, quit Claude Code, then run claude --resume d6-lab. Expected: the conversation comes back in full; open the rewind menu once more to confirm the resumed session can still rewind (checkpoints are saved with the session).
6. Open a branch: run /branch try-b. Expected: two session IDs printed; chat something casual on the branch, then /resume d6-lab back to the mainline and confirm it hasn't been contaminated.

How to know you've learned it

• Without notes, you can state when checkpoints are created automatically, how many are kept, what they're saved with, and the four classes of changes rewind can't touch (bash, subagents, out-of-session, sym/hardlinks).
• You can explain the difference between the rewind menu's three Restore and two Summarize actions, why Summarize never touches disk files, and when to use it versus /compact versus /branch.
• All 6 hands-on steps completed, with the step-4 blind-spot experiment matching the prediction.
• Self-check: in a session, Claude first ran rm data.csv via bash, then edited main.py with its editing tool; after /rewind with "Restore code", what state is each file in? (Answer: main.py is restored, data.csv doesn't come back — bash changes aren't tracked; only git can recover it.)