Claude Code checkpoints: undo Claude's changes with /rewind
From the work/ 12 min read
Every prompt you send leaves a checkpoint. /rewind, or Esc twice, rolls back the code, the conversation or both. What it misses, and when git is the right tool.
- AI
- Claude Code
- Git
In this article (7)
Claude Code checkpoints save the state of your files before every prompt you send. To undo what Claude did, type /rewind or press Esc twice with an empty prompt, pick the prompt to go back to, and restore the code, the conversation or both. Rewind never touches git, and it cannot undo files that only a Bash command changed.
Below: how checkpoints work according to the official checkpointing docs (checked on November 2, 2026), what each menu option does, what falls outside, and how to split the work with git. The menu is interactive, so what we say about it comes from the docs; in Claude Code 2.1.238, the version installed here, we confirmed the command and its options exist. The git output comes from a scratch repository. If you do not work with branches and small commits yet, start with a git workflow for AI coding agents.
What Claude Code checkpoints are
A checkpoint is a snapshot of your files taken right before Claude starts working on a prompt. Claude Code creates them on its own, with nothing to turn on: every prompt you send that starts a turn creates a new one. What it stores are copies of the files Claude changes with its file editing tools, taken before each edit. Those tools are Write, Edit and NotebookEdit, per the Agent SDK checkpointing page, which uses the same mechanism.
Scroll the figure sideways to see all of it
Three facts from the docs worth knowing before you rely on them:
- How many. Claude Code keeps file snapshots for the 100 most recent checkpoints in a session.
- Where. In
~/.claude/file-history/<session>/, per the .claude directory guide. They are saved with the conversation, so/rewindstill works after you resume a session withclaude --continueorclaude --resume. - How long. A retention sweep deletes a session's snapshots, by default about 30 days after the session last saved one. If you resume an older session, the menu still lists its checkpoints, but restoring code can fail with
No files were restored, as the error reference explains.
The two settings behind this are in the settings reference. This settings.json keeps sessions for 60 days instead of 30 and leaves checkpoints on:
{
"cleanupPeriodDays": 60,
"fileCheckpointingEnabled": true
}
cleanupPeriodDaysis how many days Claude Code keeps transcripts and other application data, checkpoint snapshots included. The default is 30, the minimum is 1, and0fails validation. Keep in mind it also keeps full conversations on your disk for longer.fileCheckpointingEnableddefaults totrue. Set tofalse, Claude Code stops snapshotting files and/rewindcan no longer restore code. In/configit shows up as Rewind code (checkpoints), and theCLAUDE_CODE_DISABLE_FILE_CHECKPOINTINGenvironment variable turns it off for a single session.
It goes in ~/.claude/settings.json for every project, or in .claude/settings.json for one. We only validated the JSON: what the settings do is what the docs describe.
How to use /rewind: code, conversation or both
There are two ways to open the menu. One is typing /rewind, which also answers to /checkpoint and /undo, per the commands list. The other is pressing Esc twice while the prompt input is empty. If the input has text, double Esc clears it instead of opening the menu; the text is saved to your input history, and the Up arrow brings it back, as the interactive mode page notes.
The menu lists the prompts you sent during the session. Pick the point, then one of these actions, named exactly as they appear on screen:
| Option | Your code | The conversation |
|---|---|---|
| Restore code and conversation | Back to that point | Back to that point |
| Restore conversation | Stays as it is | Back to that message |
| Restore code | Back to that point | Stays as it is |
| Summarize from here | Unchanged | Summarizes from that point to the end |
| Summarize up to here | Unchanged | Summarizes what came before, keeps what came after |
| Never mind | Unchanged | Unchanged: back to the list |
The two code restore options only appear when the selected checkpoint has tracked file changes to revert; otherwise the menu offers Restore conversation, the two summarize options and Never mind. After restoring the conversation or choosing Summarize from here, the original prompt goes back into the input field so you can re-send or edit it.
Which one to pick depends on what went wrong:
- The code is wrong, but the conversation is useful: Restore code. Claude keeps the discussion, and you can ask for a different approach.
- Claude went the wrong way from the start: Restore code and conversation, then rewrite the prompt with what you learned.
- The code is fine, but the conversation is full of failed attempts: Restore conversation, or a summary if all you need is context space.
Summaries do not change files: they work like a targeted /compact, and the original messages stay in the transcript. If what you want is to try another path without losing the current one, the docs point to /branch or claude --continue --fork-session instead.
Two details that trip people up. A message you typed while Claude was still working can be marked No code restore: it has no checkpoint of its own, so pick the prompt that started that turn. And if you restore the conversation and quit Claude Code without sending another prompt, the messages you removed can come back when you resume: send a prompt before you exit.
What rewind does not undo
This is the part that matters most, and the docs spell it out under Limitations. A checkpoint holds the files Claude edited with its own tools. Everything else is outside it:
- Bash commands. A file that only a command changed (
rm,mv,cp,sed -i, a formatter,npm install) is not tracked and stays as it is. The exception: once Claude has edited a file with its tools in the conversation,/rewinddoes undo what Bash did to that file afterward. - Subagents. Their edits usually do not make it into your checkpoints. Only a skill with
context: forkrunning in the foreground is restored; whatever any other subagent changed in files Claude had not touched stays. - External changes. Edits you make by hand outside Claude Code, and edits from another session running at the same time, are normally not captured unless they touch the same files as the current session.
- Symlinks and hard links. They are skipped on restore, with a
Restored the code, but skipped N fileswarning. That covers files pnpm hard-links into place and config files a dotfile manager symlinks into your project. - Directories. The Agent SDK page notes that creating, moving or deleting directories is not undone.
And one consequence of a checkpoint being a copy of files: anything that is not a file in your project does not come back either. A git commit or git push Claude ran through Bash, a migration applied to your database or a deploy are all still done after the rewind.
Scroll the figure sideways to see all of it
We reproduced it in a scratch repository with a session where Claude adds free shipping. With its tools it edits src/shipping.js and creates src/shipping.test.js; through Bash it deletes src/coupons.js and runs sed -i on src/cart.js. We simulated those actions with shell commands so the run can be repeated. This is what git shows afterward:
$ git status --short
M src/cart.js
D src/coupons.js
M src/shipping.js
?? src/shipping.test.js
$ git restore src/cart.js src/coupons.js
$ git status --short
M src/shipping.js
?? src/shipping.test.js
M src/cart.js: changed by thesed -iBash ran, and Claude never edited it with its tools./rewindleaves it alone.D src/coupons.js: deleted withrm./rewinddoes not bring it back.M src/shipping.js: edited by Claude's Edit tool. Restore code does restore this one.?? src/shipping.test.js: a new file Claude created with Write. Per the Agent SDK page, a rewind deletes the files Claude created and restores the ones it modified.git restorebrings the two Bash files back from the index, which here matches the last commit (see git-restore). The second list shows what is left: exactly what a rewind does cover.
That is why it pays to run git status after every rewind: it tells you whether something the checkpoint could not see is still there.
Rewind vs git: when to use each
The docs put it this way: checkpoints are for quick, session-level recovery, and git remains your permanent history and the way you collaborate. The Claude Code best practices say the same: checkpoints work alongside git, not instead of it. In practice the split looks like this:
| Situation | Use |
|---|---|
| Claude went wrong a few prompts ago, in this session | /rewind, Restore code |
| The conversation drifted, but the code is fine | /rewind, Restore conversation |
| A Bash command deleted, moved or reformatted files | git status and git restore |
| A subagent changed files Claude had not touched | git restore |
| You want to shelve the attempt and start clean | git stash push -u |
| The change is good | git add and git commit on the agent's branch |
| Another session, another person, or more than 30 days later | git |
The order we use: a safe point in git before you ask, rewind for mistakes from the last few minutes, and git again when the work is done. The safe point is four commands:
$ git status --short
M README.md
$ git add -A
$ git commit -m "Document shipping"
[main 80ae09a] Document shipping
1 file changed, 1 insertion(+)
$ git switch -c agent/free-shipping
Switched to a new branch 'agent/free-shipping'
git status --shortshows uncommitted work of your own: a modifiedREADME.md.git add -Aandgit commitsave it. The80ae09ahash is a point you can return to even after the session is gone.git switch -ccreates the agent's branch and switches to it, so whatever Claude does stays offmain.
If the attempt does not convince you but you do not want to throw it away, shelve it with git stash:
$ git stash push -u -m "free shipping attempt"
Saved working directory and index state On agent/free-shipping: free shipping attempt
$ git status --short
$ git stash list
stash@{0}: On agent/free-shipping: free shipping attempt
-uincludes new files git does not track yet, like the test Claude created; without it they would stay in your folder.-mnames the entry so you can recognize it in the list.- The empty
git status --shortconfirms the folder is back at the last commit. git stash listshows what you set aside.git stash popbrings it back when you need it, andgit stash dropthrows it away.
Scroll the figure sideways to see all of it
To undo a commit the agent already made, or one you already pushed, the tools are git reset on its branch or git revert. We go through both step by step in a git workflow for AI coding agents.
Common mistakes
- Assuming rewind undoes everything the agent did. It only restores what Claude edited with its own tools. What it did through Bash, what subagents did and what you changed by hand are still there: check
git statusafterward. - Using checkpoints instead of commits. They live on your machine, tied to one session, and the sweep deletes them after 30 days by default. Your team never sees them, and they do not move to another computer.
- Pressing Esc twice with text in the prompt. It clears the text instead of opening the menu. The Up arrow brings it back, or just type
/rewind. - Quitting right after restoring the conversation. The messages you removed can return when you resume. Send a prompt before you exit.
- Expecting rewind to undo a subagent. If you hand a big change to a background subagent, work on a branch and revert with git.
- Restoring the code and skipping the diff. Going back to an earlier point does not guarantee what is left is right. Review the diff and the tests as you would any agent change, including tests it may have deleted or skipped: see the agent passed the tests by deleting them.
Frequently asked questions
Does rewind delete new files Claude created?
Yes, if Claude created them with its tools. The Agent SDK checkpointing page, which uses the same mechanism, says a rewind deletes the files Claude created and restores the ones it modified. It does not undo creating, moving or deleting directories, nor files a Bash command generated, such as the output of npm install.
Can I use /rewind after closing Claude Code?
Yes. Checkpoints are saved with the conversation: resume the session with claude --continue or claude --resume and open the menu. The limit is the retention sweep, by default about 30 days after the session last saved a snapshot; after that, restoring code can fail with No files were restored. To keep them longer, raise cleanupPeriodDays.
Does rewind undo a git commit?
No. A commit is a Bash command writing inside the .git folder, and that is outside your checkpoints. If Claude edited files and then committed them, Restore code can put those files back in your working folder, but the commit stays in the history. To remove it, use git reset on the agent's branch, or git revert if you already shared it.
Does it work in non-interactive mode or in CI?
The /rewind menu belongs to interactive mode. In a -p run or an Agent SDK session, Claude Code ignores fileCheckpointingEnabled: the SDK turns checkpointing on with its enableFileCheckpointing option and restores with rewindFiles(), and a bare -p run needs CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true. In CI, our recommendation is to rely on git: every run starts from a commit.
Checklist
- A clean
git statusand the agent's branch created before the first prompt. - You know how to open the menu:
/rewind, orEsctwice with an empty prompt. - You pick the option by what went wrong: the code, the conversation or both.
- After a rewind, you check
git statusfor anything Bash left behind. - Whatever a command deleted, moved or generated comes back with
git restore, or gets shelved withgit stash push -u. - You review and revert background subagent changes with git.
- Anything worth keeping ends up in a commit: a checkpoint is not history.
- If you resume old sessions, you raised
cleanupPeriodDays.
Rewind lets you experiment without fear inside a session; git keeps what you decided to keep. To get fewer things wrong in the first place, ask for a plan before Claude touches any file with Claude Code plan mode, work with small commits and a branch for the agent, and review its tests with three checks for tests an agent changed.
Saw this on Instagram? Comment REWIND on the Reel and I'll send you the guide.
Written by

Published November 3, 2026