Twenty minutes into a refactor the agent takes a wrong turn: three files reorganised around an abstraction I do not want. Before checkpoints existed, that cost me a git checkout I had to think carefully about, or a stash, or a small pile of hand-written reverts.
Now it costs two taps of Escape.
Checkpointing is one of the best things Anthropic has put into Claude Code. It removed a real tax on experimenting, and it did it without asking me to change how I work. The tip card in the product sells it as "Undo anything", and adds, correctly, that your git history stays clean.
It is worth knowing precisely what that covers, because the feature gets much more useful once you can see its shape. The boundaries are documented, they are sensible, and they follow one rule you can hold in your head.
What a checkpoint actually is
Claude Code captures the state of your code before each prompt you send. Under that, it backs up individual files before it modifies them through its file editing tools: Write, Edit and NotebookEdit. Your prompts become the restore points.
A few numbers worth knowing:
- 100 checkpoints per session. Discarding an older one deletes the snapshot files no remaining checkpoint still references, with one exception: each file's first snapshot survives, because the VS Code extension uses it as the baseline for its session diffs.
- Checkpoints are saved with the conversation, so
/rewindstill works after you resume a session days later. - They are deleted along with sessions after 30 days, which you can change with
cleanupPeriodDays.
The whole thing is a toggle, listed in settings as "Rewind code (checkpoints)". It is not available in cloud sessions yet.
Esc Esc, and the six doors
Run /rewind, or press Esc twice while the prompt input is empty. That last detail catches people: if there is text in the input, a double Esc clears it instead of opening the menu. The cleared text goes to your input history, so Up brings it back once you are done.
The menu lists every prompt you sent this session. Pick one, then pick an action:
| Action | What it does |
|---|---|
| Restore code and conversation | Both go back to that point |
| Restore conversation | Rewinds the messages, leaves your files as they are |
| Restore code | Reverts the file changes, keeps everything the model learned |
| Summarize from here | Compresses the conversation forward from that point |
| Summarize up to here | Compresses everything before it, keeps later messages intact |
| Never mind | Back to the list, nothing changed |
The two code options only appear when the selected checkpoint actually has tracked changes to revert. A menu that hides the button it cannot honour saves you testing every restore to find out whether it did anything.
Restoring the conversation puts the original prompt back in your input box, ready to edit and re-send. That is the loop the feature was built for: go back to before the detour, say it better, go again.
The two summarize options are a targeted /compact that you aim at a specific stretch of the session. Files on disk are untouched, and the original messages stay in the transcript, so nothing is actually lost. Highlight the option and type into the add context (optional) row to steer what the summary keeps.
If you want to keep the original session intact and try a second approach alongside it, that is /branch or claude --continue --fork-session instead. All of this sits next to the rest of the context budget, and summarize is the most precise of them.
One nice touch: if you ran /clear earlier in the same process, the top of the rewind list offers /resume <session-id> (previous session). You can walk back past a clear you regret, on 2.1.191 and later.
What it tracks, and what git keeps
Here is the rule the whole feature runs on: checkpointing covers the edits the main agent makes through its own file editing tools. Everything else stays git's job.
| Covered | Not covered |
|---|---|
Write, Edit and NotebookEdit changes | Anything a bash command changed (rm, mv, cp, sed -i) |
| Files created during the session | Directories created, moved or deleted |
| Files modified during the session | Edits from other concurrent sessions, and your own by hand |
| Local files | Remote and network files |
That division is defensible. The tool can snapshot its own edit path cheaply and exactly. It cannot know what npm install or a formatter or a migration did to your working tree, so it does not pretend to.
The practical consequence: the more of a task runs through bash, the more of it belongs to a commit rather than a checkpoint. A session of careful file edits is fully covered. A session that runs a codemod, regenerates a schema dump and rewrites a lockfile is mostly not.
Two more things that follow from the rule and are easy to miss. A restore deletes the files the agent created since that point, so it is a true revert rather than an additive one. And checkpoints are tied to the session that made them.
The subagent rule worth memorising
This is the one I would put on a sticky note, because it is the least intuitive part and it is precisely knowable.
A subagent edits files with the same tools the main agent uses, but those edits usually land outside your session's checkpoints. Whether rewinding brings them back depends entirely on how it ran:
- A skill with
context: forkrunning in the foreground edits your working tree during your own turn, so rewinding restores its edits like any other. - Every other subagent is not restored. That includes a forked skill running in the background, which is the default, and a background
/code-review --fixrun. Use git.
So the same skill is covered or not covered depending on one frontmatter flag. If you fan work out across parallel agents in worktrees, your safety net there is the branch, exactly as it was before checkpointing existed.
When a restore skips a file
Since 2.1.216, a restore refuses to write through a tracked path that has become a symlink, a hard link, or another non-regular file. It also skips a file whose parent directory no longer resolves to where it was at checkpoint time, or whose backup it cannot read safely. You get a Restored the code, but skipped N files warning, and the skipped files keep their current contents.
Two ordinary setups land in this category: config files that a dotfile manager symlinks into your project, and anything pnpm hard-links into place.
That is the right trade. Before 2.1.216 a rewind wrote and deleted straight through those links, silently, which is a much worse outcome than a warning. To see exactly which paths a restore skipped, turn on /debug before you restore and read ~/.claude/debug/<session-id>.txt.
Rewinding from a script
The same machinery is available outside the interactive session. In the Agent SDK, set enableFileCheckpointing: true (or enable_file_checkpointing=True), add replay-user-messages so user messages arrive with UUIDs, keep the UUID you want, and call rewindFiles() or rewind_files(). Note that this restores files only, the conversation stays where it is.
From the CLI it looks like this:
CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>The flag is standalone, it needs --resume, it refuses to run alongside a prompt, and it does not show up in claude --help. Without the environment variable you get "File rewinding is not enabled", which is the error I would have spent an hour on if the docs had not said so first.
That gives you a useful pattern for unattended runs: keep the UUID of the last known-good turn, and roll the files back automatically when your own validation fails.
How I use it
Rewind is my default response to a bad direction, and it has changed how freely I let an agent try things. Two taps, back to before the detour, re-send a better prompt. No branch, no stash, no reverts to read.
Around that, one habit does all the work: commit before handing off anything substantial. Rewind is reliable within its boundary, and the commit covers the other half. Bash changes, subagent output, the directory it moved, the session you closed last Thursday.
The docs say it plainly, and it is the right way to hold it: checkpoints are for quick, session-level recovery, and version control is for permanent history. Those are two different jobs and the tool only claims one of them.
Worth keeping in view: rewind restores your files, and the world keeps whatever already happened to it. The migration ran, the commit went out, the webhook fired. Once something has escaped the working tree you are handling an incident, and the file history serves as evidence.
Inside the working tree, though, this is the cheapest undo the tool has ever had. Learn where it stops and you can stop thinking about it.