Mastering autonomous coding sessions with Claude Code's checkpoint system

Claude Code's checkpoints make long agent sessions recoverable

Long autonomous coding sessions fail in one specific way: the agent makes ten good edits, then one bad one, and everything downstream builds on the damage. Claude Code's checkpointing answers that failure mode directly. As the official checkpointing documentation states, "Claude Code automatically tracks Claude's file edits as you work, allowing you to quickly undo changes and rewind to previous states if anything gets off track."

The recovery control is the rewind menu: run /rewind, or press Esc twice with an empty prompt, and you get a per-prompt list of the session with a choice per entry — restore code and conversation, restore conversation only, restore code only, or summarize instead. That tuple of code plus conversation is the whole point, because an agent that reverts your files but keeps believing the bad edit was correct will simply redo the mistake with full confidence.

How checkpoints actually work

Per the vendor docs, "checkpointing automatically captures the state of your code before each user prompt." Note the granularity carefully: per user prompt, not per file write. Every prompt you send creates a new checkpoint covering the file edits Claude's editing tools made during that turn. That is coarser than a per-edit snapshot — and more honest, because the unit of recovery matches the unit of intent: one instruction, one checkpoint.

Three retention facts worth knowing before you lean on this. First, Claude Code keeps file snapshots for the 100 most recent checkpoints in a session; older snapshots are discarded, except each file's first snapshot, which the VS Code extension keeps as its session-diff baseline. Second, checkpoints are saved with the conversation, so /rewind still works after you resume a session days later. Third, snapshots expire in the retention sweep about 30 days after the session last saved one — rewind past that and you can hit a No files were restored error, avoidable by setting cleanupPeriodDays. All three are straight from the checkpointing page; treat the 100-checkpoint window and the 30-day sweep as capacity numbers to plan around, not background trivia.

The substrate underneath is the session layer: conversations persist continuously to local transcript files and resume via claude --continue, claude --resume, or the /resume picker, per the session management docs. Checkpoints ride on top of that substrate — conversation restore is only meaningful because the transcript underneath is durable and re-openable.

One sourcing note: an earlier version of this article leaned on a third-party community writeup of project checkpoints for the mechanism. That piece is a blogger's account, not vendor documentation, and some of its specifics (including any CLI flags it implies) should not be treated as the product surface. Everything mechanical below is checked against the official docs; where the docs are silent, this article says so instead of filling the gap.

The rewind menu, option by option

Open it with /rewind or double-Esc on an empty prompt. The menu lists each prompt you sent this session. Pick one, then pick an action, exactly as the docs describe:

• Restore code and conversation: both halves go back. Use this when the agent's reasoning went wrong — you want the files back and the agent's beliefs back, so it does not re-derive the same bad plan.
• Restore conversation: rewind the dialogue while keeping current code. Use this when the code is fine but the conversation wandered — keep the artifact, drop the rambling.
• Restore code: revert file changes while keeping the conversation. Use this when the plan was right but the execution had a bug — the agent remembers the plan and can retry cleanly.
• Summarize from here / Summarize up to here: compress part of the conversation into a summary to free context window space, without touching files on disk.

After a conversation restore, the original prompt is dropped back into your input field so you can edit and re-send with the missing constraint added. And if you ran /clear earlier in the same process, the menu gains a previous-session entry to pull that conversation back — on Claude Code v2.1.191 or later, per the checkpointing docs. Small kindness, real sessions saved.

Why code plus conversation is the right shape

State drift kills long sessions the same way every time. The agent renames a field mid-refactor; the rename cascades into a consumer it had no map of; the conversation history insists it was a good idea while the diff says otherwise. The hard part was never the edit — it is that the agent's context is now downstream of an action it cannot safely reverse. Plain git revert fixes the files but leaves the agent composing its next change against a mental model of a world that no longer exists.

A checkpoint shaped as a filesystem-plus-conversation pair closes that loop. Rewind both and the agent re-derives from the true prior state. Rewind one half and you get the two surgical variants above. Most session-memory tooling persists one half and quietly leaks the other; the rewind menu's insistence on offering both, explicitly, is the design decision that matters here.

For teams running agents against shared code, this pairs with session branching. To try a different approach while preserving the original intact, /branch (or claude --continue --fork-session) copies the transcript into a new session, per the sessions doc. Branch to explore, rewind to recover — related tools, different jobs. Our agent session playbook covers the surrounding discipline of structuring long agent runs so they stay reviewable.

The honest limitations

The docs are unusually candid about what checkpointing does not cover. Read this section as load-bearing, not fine print — every item below is from the checkpointing limitations section:

• Bash changes are not tracked. Files modified via rm, mv, cp, or any shell command — rather than Claude's file-editing tools — cannot be undone through rewind.
• Subagent edits usually are not restored. A foreground forked skill's edits rewind normally; background subagent edits need git to revert.
• External changes are not tracked. Edits made outside Claude Code, or from concurrent sessions, are normally invisible to your session's checkpoints.
• Symlinked and hard-linked files are skipped, with a warning, keeping their current contents.

The practical consequence: checkpointing is a safety net for the agent's own edit path, not a substitute for version control. Long autonomous runs still want a clean git state before launch, atomic commits at milestones, and — for anything production-shaped — the discipline of treating agent output as untrusted until reviewed, as in our production background-jobs guide.

A workflow that uses all of it

Concretely, for a multi-hour autonomous session against a real codebase:

1. Start from a clean tree and a fresh branch. Checkpoints are not commits; the branch remains your durable history.
2. Work prompt by prompt, one intent per message. Checkpoint granularity follows prompts, so one intent per prompt gives you one recovery unit per decision.
3. When output goes sideways, /rewind to the last good prompt, choose code and conversation, then edit the re-offered prompt to add the constraint the agent missed.
4. When the code is right but context is bloating, summarize from the midpoint forward instead of rewinding — keep the artifact, shed the tokens.
5. When you want to explore an alternative without losing the current line, /branch it. Rewind is your undo; branch is your fork.
6. Commit at milestones. The 100-checkpoint window and 30-day snapshot retention are generous, but git is permanent and vendor-scoped storage is not.

None of this replaces the durable layer underneath: the components your users touch have to behave identically wherever they ship, regardless of which agent made the edits. If you want that layer handled — one component API across web, iOS, and Android that survives every model swap — start from OTF's templates instead of rebuilding it per project.

What this gets you, and what it does not

It gets you the ability to run agents for hours without holding your breath: the most expensive failure mode in autonomous coding — drift causing cascading bad edits — is now a menu selection away from recovery. It does not get you portability, since checkpoints live in one vendor's session format. It does not cover the shell path, the background-subagent path, or external edits. And it does not remove the need for git hygiene. Use the rewind menu freely, and commit like it does not exist.

Sources

• Claude Code checkpointing documentation — automatic per-prompt tracking, rewind menu actions, retention windows, limitations
• Claude Code session management documentation — resume, branch, transcript storage, rewind-menu cross-references
• Claude Code overview — the tool as an agentic coding assistant across terminal, IDE, desktop, and web
• Community checkpoint writeup — third-party account; mechanism verified against the vendor docs above