Claude Code /rewind: What It Won't Restore

The mechanic is simple. Every prompt you send creates a checkpoint, and that checkpoint holds snapshots of the files Claude touched with its editing tools. Claude Code keeps snapshots for the 100 most recent checkpoints in a session, stores them alongside the conversation so they survive a resume, and deletes them with the session after 30 days. You can move that window with cleanupPeriodDays in settings.

You open the menu with /rewind, or by pressing Esc twice on an empty prompt. Pick a message and you get up to five actions: restore code and conversation, restore conversation only, restore code only, or summarize forward or backward from that point. The two code options only appear when that checkpoint actually captured file changes.

That last sentence is the tell. If a turn changed files but the code options never appeared, the changes were made somewhere checkpointing does not watch.Most people read the missing option as “nothing changed” and move on. It usually means the opposite.

This is the big one, and Anthropic documents it plainly: checkpointing does not track files modified by bash commands. rm, mv, cp — none of it comes back. Extend that list honestly and it gets uncomfortable, because it also covers sed -i, heredoc redirects, npx prettier --write, a codemod, a database migration, and every generated file a build step drops on disk.

Here is the part nobody warns you about: the more autonomy you give an agent, the smaller its checkpoint coverage gets. The permissive modes people turn on for long unattended runs actively push the model toward shell edits, because a sed one-liner is cheaper than a structured edit call. I run agents that way on purpose for bulk work. The trade is real: the faster the run, the less of it /rewind can undo.

So the rule I actually use is a question, not a policy. Before a risky turn: if this goes wrong, do I want to undo it with rewind? If yes, I say so in the prompt — edit the file, don't script it. If no, I commit first and let it rip. What I stopped doing is assuming rewind would cover a turn I never looked at. The same reasoning applies to what the Claude Code sandbox actually blocks — the guardrail has a precise shape, and it is not the shape most people assume.

A subagent edits with the same file editing tools the main loop uses, so you would reasonably expect its work to land in your checkpoints. Usually it doesn't. The distinction is where the subagent runs:

• Foreground fork — a skill running with context: fork and background: false edits your working tree during your own turn, so rewind restores it normally.
• Everything else — background forked skills (the default), delegated agents, a background code review that applies its own fixes. Rewind does not bring those edits back. Git is the only way out.

Read that second bullet next to how people actually work now. Fan-out is the whole point of agent teams and subagents, and the default for a forked skill is background. The workflows with the widest blast radius are exactly the ones checkpoints cover least.

The fix is boring and it works: commit before you fan out, and give parallel agents isolated git worktrees when they might touch the same files. A worktree turns “which of these six agents broke the build” into a directory you can delete. If you are deciding what should be a skill versus a delegated agent in the first place, that trade-off has its own rules — and reversibility belongs in the decision.

When you choose a code restore, Claude Code walks the tracked paths and skips any that is a symlink or a hard link, then tells you: Restored the code, but skipped N files. Those files keep their new contents. The restore reports success. Your tree is half-reverted.

This sounds exotic until you look at a real machine. Two setups hit it constantly:

• pnpm. It hard-links packages out of a content-addressable store by design. Any repo on pnpm has a node_modules full of hard links.
• Symlinked config and shared tooling. Dotfile managers do it, and so does any single-source-of-truth layout — mine included. I keep one skill library and symlink each client's directory at it, which is exactly the pattern I described in the portable SKILL.md post. Every one of those symlinked skill folders is a path a restore will decline to touch.

If a restore mentions skipped files, turn on /debug before restoring next time — the debug log at ~/.claude/debug/<session-id>.txt names each skipped path so you can fix them by hand instead of guessing.

Checkpointing tracks files edited within the current session. Your own manual edits in your editor are not captured. Neither are edits from a second Claude Code session running in another terminal on the same repo — unless it happens to touch a file the current session already touched, which is the worst kind of “sometimes.”

If you run two or three sessions across a monorepo, or you have crons kicking off agent runs on a schedule, checkpoints stop being a coherent picture of the repo very quickly. They are per-conversation, not per-project. Layering hooks that enforce checks on every edit gets you far more real safety than trusting a rewind you have never tested.

Two rows green, six rows red. That ratio is the whole article. It is not a criticism of the feature — checkpointing does precisely what its documentation says it does, and the official checkpointing pageis unusually honest about the limits. The problem is that “rewind” is a word with a promise baked into it, and the promise is bigger than the feature.

I run blog publishing, infra remediation, and client automation as scheduled agent jobs — unattended runs, no human watching the diff. After one of them cleaned up files through the shell and left me with a rewind menu that could only offer “restore conversation,” I stopped treating checkpoints as a backstop. Five things replaced it, in the order they pay off:

1. Commit before every autonomous run. A scratch branch and one commit. Three seconds, and it is the only control that covers shell edits, background subagents and linked paths simultaneously.
2. Say “edit the file” when you want coverage. If a change is risky and you want checkpoint protection, ask for a structured edit instead of a shell rewrite. You are trading a little speed for an undo.
3. Isolate fan-out in worktrees. Parallel agents sharing one working tree produce changes rewind cannot take back. A worktree per agent makes the blast radius a folder.
4. Read the skipped-files warning. It is not cosmetic. Those paths still hold the new contents, and nothing else will tell you.
5. Verify with git status, not with the menu. The menu reports what it reverted. Only the diff reports what is still changed.

Anthropic's own guidance lands in the same place: checkpoints are for quick session-level recovery, and for permanent history you keep using git. Rewind handles the turn you regret. Git handles everything rewind cannot see.

None of this means don't use it. Inside its scope, rewind beats git for speed, and there are three cases where I reach for it first.

Exploring two approaches. Try the first implementation, rewind code and conversation, try the second. No branch, no stash, no commit message you will never read again.

Killing a bad turn immediately. When a single prompt produced a mess and you caught it in the same breath, restore code and conversation, then edit the prompt that gets handed back to you and re-send it. That last detail is the underrated part — the original prompt returns to the input field so you can fix the instruction rather than retype it.

Reclaiming context without losing the thread. The summarize options are the sleeper feature here. Summarize from here compresses a verbose debugging tail while keeping your original instructions intact; summarize up to here does the reverse. Both leave the real messages in the transcript, so Claude can still go back for detail. It is a targeted /compact, and on a long session it is worth more than the undo.

• Checkpoints capture only what Claude changes through its file editing tools. Shell edits — sed, heredocs, formatters, migrations — are invisible to /rewind.
• Background subagents don't rewind. Only a foreground forked skill running inside your own turn does. Fan-out and reversibility pull in opposite directions.
• Symlinked and hard-linked paths are skipped during a restore and keep their new contents. pnpm repos and symlinked config hit this constantly.
• Checkpoints are session-scoped: 100 per session, 30-day expiry, blind to your manual edits and to any other session on the same repo.
• If the code-restore option never appears for a turn that clearly changed files, that's not 'nothing changed' — that's zero coverage.
• Commit before every autonomous run. It's the one control that covers all four blind spots at once.