Contents
"I let Claude Code run, and the change went somewhere I didn't want." For exactly that moment, checkpointing and /rewind let you roll back to "before it went wrong" in a couple of keystrokes. Claude Code automatically snapshots state before each edit, and you can return to a previous state with /rewind or Esc twice.
This article covers, based on the official documentation, what checkpointing is, how to use it, what is and is not restored (most important), how it differs from Git, using it to recover from errors, and availability. The key points up front. ① It automatically tracks file edits, and each prompt becomes a restore point. ② Open the menu with /rewind or Esc twice and choose to restore code, conversation, or both. ③ But only "Claude's file edits" are restored—changes made by bash commands or outside Claude are not. That is why it is not a replacement for Git.
Roll changes back to "before it went wrong"
— each prompt is a restore point; return with Esc twice
1. What checkpointing and /rewind are
The official definition: "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." A snapshot is taken automatically before each edit, and on top of that every prompt you send creates a new checkpoint (a point you can return to). Checkpoints persist across sessions, so you can access them in resumed conversations too.
In other words, this feature means "even if you hand things to the AI and it goes wrong, you can return to a safe point in a few keystrokes." In interactive Claude Code (the CLI), /rewind is automatic and on by default.
2. How to use it (/rewind and Esc Esc)
There are two ways to open the rewind menu: type /rewind, or press Esc twice when the prompt input is empty.
⚠️ A note on Esc Esc: if the input contains text, pressing Esc twice clears the input instead of opening the menu. The cleared text is saved to your input history, so press the Up arrow to recall it. To be sure the menu opens, clear the input first.
The menu lists each prompt you sent during the session. Pick the point you want, then choose an action.
| Action | What it does |
|---|---|
| Restore code and conversation | Revert both to that point |
| Restore conversation | Rewind to that message but keep current code |
| Restore code | Revert file changes only, keep the conversation |
| Summarize from / up to here | Compress context (not a rewind; files unchanged) |
| Never mind | Exit without changes |
After "Restore conversation" (and similar), the original prompt from the selected message is restored into the input field, so you can re-send or edit it. "Restore code" while keeping the conversation lets you rephrase, informed by what went wrong—this is the flow you'll use most in practice.
3. What is and is not restored (most important)
This is the most misunderstood part of the feature. Checkpointing tracks only "changes made by Claude's file-editing tools (Write / Edit / NotebookEdit)." Any other side effect is not undone by rewinding.
⚠️ Not restored (stated in the official docs)
- File changes by bash commands:
rm file.txt,mv old.txt new.txt,cp source dest, etc. cannot be undone through rewind - Changes outside the session / from other sessions: manual edits and concurrent sessions' edits aren't captured unless they touch the same files
- Creating, moving, or deleting directories / remote or network files
Database state, migrations, package installs, network calls—any "side effect that isn't a file edit" is likewise not reverted (the docs don't spell this out, but since only file changes via the edit tools are tracked, it follows logically). In short, remember that only "the contents of files Claude rewrote with its edit tools" can be restored. And because Claude can also change files via Bash, the safe practice is to not over-rely on rewind and to commit to Git at milestones.
4. How it differs from Git
The docs frame it as "checkpoints are local 'undo,' and Git is 'permanent history'" and state plainly that "checkpoints complement but don't replace proper version control."
- Automatic, instant, no setup
- Ideal for in-session experimentation
- Covers edit-tool file changes
- Cleaned up after 30 days (configurable)
- Commits, branches, long-term storage
- Records bash changes too
- Shareable and reviewable in a team
- Doesn't disappear (until you delete it)
The division of labor is simple: checkpoints for quick in-session undo, Git commits for durable history. Commit at the milestones of a larger task, and you can safely return even across what rewind can't cover (such as bash changes).
5. Recovering from errors
/rewind is also a recovery tool when the conversation breaks and can't continue. Claude Code's official error reference, for the 400 error related to tool-use concurrency and thinking blocks, has the product itself say: "API Error: 400 ... Run /rewind to recover the conversation." Press Esc twice to step back to a checkpoint before the corrupted turn and continue from there. This is also the main recovery for the court / invoke tag-leak (tool_use concurrency) error.
⚠️ Version note: if you're on Opus 4.7 / 4.8, run claude update first. Per the docs, versions before v2.1.156 can trigger this error during normal tool use, and /rewind does not clear it. Updating comes first.
If rewind can't reach the cause (e.g. corruption from context compaction), you can also start fresh with /clear. For handling errors in general, see the Claude Code error roundup.
6. Availability and retention
In interactive Claude Code (the CLI), it's automatic and on by default—no special setup. In the Agent SDK, by contrast, it's an explicit opt-in (e.g. enableFileCheckpointing); keep the two distinct.
For retention, checkpoints are cleaned up along with sessions after 30 days (configurable). The docs don't spell out the on-disk storage location, an on/off toggle, or the specific config key for the retention period, so this article doesn't assert them (check the official docs for the latest). The feature shipped in Claude Code v2.0.0 (September 2025) and was reported at the time as "the most requested feature" (release date and background are from secondary sources).
Summary
Checkpointing and /rewind are a safety net that automatically tracks Claude's file edits and lets you roll back to "before it went wrong" in a few keystrokes. Each prompt becomes a restore point, and you open the menu with /rewind or Esc twice to revert code, conversation, or both. In practice, the central flow is "Restore code while keeping the conversation," then rephrase.
The key caveat: "only Claude's file edits are restored"—bash-command changes, external changes, directory operations, databases, and the like are not. So it's not a replacement for Git; commit at milestones as a rule. And /rewind also recovers a broken conversation, such as the 400 error (on old versions, claude update first). Related: the court/invoke error, Claude Code errors, hooks.
FAQ
Q. What is checkpointing for?
A. It's a safety net for quickly rolling changes back to "before it went wrong." Claude Code takes a snapshot automatically before each edit, and each prompt you send becomes a restore point. Even if you hand things to the AI and it goes wrong, you can return to a previous state with /rewind or Esc twice. In the interactive CLI it's on by default.
Q. How do I use it?
A. Type /rewind, or press Esc twice when the input is empty, to open the menu. From the list of prompts you sent, pick the point to return to and choose "Restore code and conversation," "Restore conversation," or "Restore code." The most common is "Restore code (keep the conversation)," then rephrase your instruction, informed by what went wrong. Note that if the input contains text, Esc twice clears it instead.
Q. Are files created or deleted by bash restored too?
A. No. Only file changes made by Claude's edit tools (Write / Edit / NotebookEdit) are restored. Changes by bash commands (rm, mv, cp, etc.), changes outside the session or from other sessions, creating/moving/deleting directories, and remote files are not undone by rewind. The same goes for "side effects that aren't file edits," like database state. That's exactly why you should commit to Git at milestones.
Q. Does it replace Git?
A. No. The docs frame it as "checkpoints = local undo, Git = permanent history," stating it complements but doesn't replace version control. Checkpoints are best for quick in-session undo and are cleaned up after 30 days (configurable). Keep using Git for commits, branches, long-term storage, and team sharing.
Q. Can I use it when an error blocks the conversation?
A. Yes. For the 400 error related to tool-use concurrency or thinking blocks, the product itself says "Run /rewind to recover the conversation." Press Esc twice to step back to before the corrupted turn and continue. But versions before v2.1.156 may not clear it via /rewind, so on Opus 4.7 / 4.8 run claude update first. See also the court/invoke error article.
