Original URL: https://getagenttools.com/blog/claude-code-checkpoints/ # Claude Code Checkpoints: Rewind Edits and Check Recovery Limits 6 Oct 2026Marek. - claude-code - agent-ops - git An agent takes the wrong turn, and you want to go back. Fair enough. But back to what? The files before the change, the conversation before the bad assumption, or both? With Claude Code checkpoints, that choice matters more than finding the rewind command. I would keep the diagnosis and discard the bad implementation if the discussion had finally exposed the real problem. Restoring both would throw away useful work. The reverse is possible too: the patch is fine, but the conversation needs a different direction. Recovery should follow what you want to retain. - **The choice:** code and conversation can need different recovery points. - **The boundary:** a user prompt starting a turn creates a checkpoint; a steering message inside the turn does not. - **The files:** editing-tool changes and shell writes have different coverage. - **The other work:** most subagent edits and external effects need separate handling. - **The baseline:** reviewed Git commits remain useful when a session snapshot is missing or incomplete. The broader [Claude Code](https://getagenttools.com/tools/claude-code/) review covers the tool. The behavior below comes from its current documentation. The tracked-edit versus shell-write example is an exercise to run in a disposable repo, not a native rewind test I have completed for this article. ## Start with what you want to keep `/rewind` opens the available points and recovery choices. You can restore code, conversation or both, and summarize part of a conversation. Branching the conversation is another option when you want to explore a different direction without losing the current one. See the [commands reference](https://code.claude.com/docs/en/commands). If you understand the mistake now, keep that understanding. Restore the code and ask for a new implementation using the diagnosis. If the files are useful but the conversation keeps pulling the agent toward a discarded approach, restore the conversation instead. Both is the right choice when you want to retry the task from an earlier state altogether. Write that decision in one sentence before selecting anything. "Keep the explanation, restore the parser" is enough. It gives you a file to inspect and makes it harder to throw away the part you meant to save. In the terminal, double `Esc` opens rewind when the input is empty. If there is text in the input, it clears the text instead. When that distinction is inconvenient, use `/rewind`. The shortcut behavior is in [interactive keyboard controls](https://code.claude.com/docs/en/interactive-mode). ## A message is not always a new recovery point Claude's documented checkpoint boundary is a user prompt that starts a turn. A correction sent while that turn is still running does not create another checkpoint. File tracking also follows Claude's editing tools, not everything that happened to the directory. See [checkpoint tracking](https://code.claude.com/docs/en/checkpointing). Suppose you request a refactor, notice a bad direction and send a correction before it finishes. There may be no separate point immediately before that correction. Stop and inspect the available points. The order of messages you remember is not enough to identify what can be restored. For a change with a clear check, I prefer a bounded turn: make the change, inspect it, then request the next one. It gives the session a sequence you can understand. That is an operating preference, not a promise about checkpoint coverage. Bundling a refactor, dependency upgrade and deployment into one request makes the recovery question harder. Each can leave a different kind of state behind. A checkpoint does not make them one reversible operation. ## The shell-write problem Bash file changes are outside checkpoint tracking. A successful rewind therefore cannot establish that a formatter, generator or other shell command was undone. The [documented limitation](https://code.claude.com/docs/en/checkpointing#bash-command-changes-not-tracked) is explicit. To check the distinction, use a disposable committed repo with `tracked-example.txt` and `shell-example.txt`. Give both known baseline contents. Ask Claude to change the first with its file editing tool. In a separate task, ask it to write the second through a shell command. Inspect the diffs and tools used before selecting a checkpoint; inspect the two actual files afterward. The point of the exercise is the difference between those files. The menu saying recovery finished would not answer it. This guide has no native before-and-after result for that exercise, so the documented behavior should not be mistaken for a measured run. Mixed histories need care as well. A file can first be edited through a tracked tool and then changed by a generator. Look at every relevant output rather than assuming the last tool used describes the whole turn. A reviewed Git commit provides a baseline outside the session. After recovery, `git status --short` and `git diff` show what is currently in the working tree, including changes rewind did not cover. See [Git status](https://git-scm.com/docs/git-status) and [Git diff](https://git-scm.com/docs/git-diff). ## A parent session does not own every edit Current Claude documentation says most subagent edits are not restored by the parent's rewind. It names an exception: a foreground forked skill, using `context: fork` and `background: false`. That exception does not apply to every delegated task. See [subagent checkpoint behavior](https://code.claude.com/docs/en/checkpointing#subagent-edits-not-restored). Ask for the changed paths and diff before deciding what to reverse. A parent conversation can contain the subagent's report while its checkpoint does not cover the subagent's files. Those are separate things. If another session or a person is also editing, pause that work first. Do not overwrite an uncommitted contribution because it happens to sit in the same directory as the agent's mistake. When the edit history is unclear, save the current contents before recovery. That preserves the option to compare instead of forcing you to trust a guess. Symlinked and hard-linked paths can be skipped during restore, with a warning. Read it. A skipped file is still a file you need to inspect, not a footnote to an otherwise successful operation. The [linked-path limitation](https://code.claude.com/docs/en/checkpointing#symlinked-and-hard-linked-paths-not-restored) covers that case. At the end I want to see the intended files in the intended state. "Rewind completed" is too broad for a task with several editors and tools. ## What happened outside the checkout stays outside it A sent message, API request, database write or deployment has its own recovery mechanism. Restoring a local file does not send a message back, reverse a transaction or restore a deployed service. Inspect the service's history and controls. Before allowing such a task, name the target and how you would reverse or contain the effect. For a demonstration, use a harmless local fixture, such as a JSON file representing a pretend service, instead of a real database or recipient. If the real action already happened, stop further actions and inspect the external system. Repeating the request because the conversation was reset can create a duplicate. Keep the action log with the change so you can distinguish fixing the code from fixing what the code already did. The checkpoint feature covers file and conversation recovery. Nothing in that description supplies a remote undo. ## Resume does not put the repository back Checkpoints are saved with the session, so rewind can be available after resume. Snapshot retention still matters. An old point in the conversation is not a permanent file backup. See [checkpoint persistence](https://code.claude.com/docs/en/checkpointing). Use the [Claude resume guide](https://getagenttools.com/blog/claude-resume/) to find the right session, then check the directory, branch and current files. The repository may have changed since that conversation last ran. If the real problem is an overloaded context window, summarization is a different choice from restoring code. Keep the unresolved failure, relevant paths and the check you still need in the summary instructions. The [context window guide](https://getagenttools.com/blog/claude-code-context-window/) covers compaction and what a long session needs to retain. When a restore reports no files or skipped files, inspect the current state and use a retained baseline. Repeating a destructive action to recreate a missing checkpoint is a bad trade. A preserved copy or Git commit gives you something concrete to recover from. ## The role Git still has I would use checkpoints to reconsider a local direction during a session, and commits for work I need to preserve, compare or share. Commit after the relevant checks pass, before beginning a materially different experiment. The next task then has a baseline that does not depend on remembering a conversation. Choose a Git restore by source and paths, after inspecting the diff and keeping needed uncommitted work. `git restore` can replace working-tree contents; its staging and source options affect what it changes. The [restore reference](https://git-scm.com/docs/git-restore) is worth reading before using it as a recovery shortcut. A good recovery instruction says what to restore and what to retain. That is enough to make the result understandable to the next operator. ## How does this compare with Codex worktree recovery? Codex desktop saves a snapshot before deleting a managed worktree and offers restoration when the associated chat is reopened. Its [worktree cleanup and recovery documentation](https://learn.chatgpt.com/docs/environments/git-worktrees#worktree-cleanup) describes that lifecycle trigger. It is different from Claude's session checkpoint menu. This comparison is documentation-based too. In either product, a restored directory still needs inspection. The chat remaining available does not tell you that its files survived, and recovered files tell you nothing about a remote transaction. ## FAQ ### What does Claude Code rewind restore? Choose tracked code edits, conversation state or both at an available checkpoint. Check the actual files and warnings afterward; the menu choice alone does not establish complete recovery. ### Does rewind undo shell commands or external API actions? Bash file changes are not tracked for rewind. External effects need recovery in the system where they happened. Inspect each separately. ### Can I rewind after resuming a session? Yes, saved checkpoints can be available after resume. Snapshot availability and the current checkout still matter, so inspect the restore rather than assuming every old point has recoverable files. ### Do checkpoints replace Git commits? No. Keep reviewed commits for durable history, shared work and known baselines. Checkpoints help with a session decision but do not cover every file change or external effect. Put this into practice [See the tool list](https://getagenttools.com/tools/)[Train your team](https://getagenttools.com/#training)