Checkpoints vs. Git: Tracing What /rewind Restores
A developer runs a single Claude Code CLI session that does the following, in order:
- Edits
src/parser.tsusing the Edit tool (prompt 1). - Runs
rm -rf build/via Bash to clear a stale build directory (prompt 2). - Edits
src/parser.tsagain, plus creates a new filesrc/parser.test.tswith the Write tool (prompt 3). - Spawns a background subagent that reviews the whole
src/folder and, using its own Edit tool, fixes a lint issue insrc/utils.ts(prompt 4).
The developer decides prompt 3's approach was wrong and runs
/rewind, selecting the checkpoint just before prompt 3 and choosing
"Restore code and conversation."
- Walk through what state each of the four changes above ends up in after this rewind: which are reverted, which survive, and why, referencing specifically what checkpointing does and does not track.
- The developer is surprised that
build/is still missing after the rewind. Explain precisely why, and what they'd need to do instead to get it back. - Explain why
/rewindis not a substitute for committing to git during this same session, using this exact scenario as the evidence.
1. State of each change after the rewind:
- Prompt 1's edit to
src/parser.ts: this happened before the restore point (before prompt 3), so it is untouched either way — "Restore code and conversation" reverts to the state at the selected checkpoint, and prompt 1's edit is part of that state. - Prompt 2's
rm -rf build/: this was a Bash command, not a call to Claude's Edit or Write tools, so checkpointing never tracked it in the first place. Rewinding to before prompt 3 does not "undo" it, because there was nothing captured to undo — thebuild/directory was already gone before the checkpoint being restored to, and stays gone after. - Prompt 3's edit to
src/parser.tsand newsrc/parser.test.tsfile: these are exactly what "Restore code and conversation to the point before prompt 3" reverts — both were made through Claude's own file-editing tools during prompt 3, both are tracked, so the second edit toparser.tsis undone andparser.test.tsis removed (or, more precisely, the working tree returns to its state before those changes existed). - Prompt 4's subagent fix to
src/utils.ts: this happened after the restore point chronologically, but the more important fact is that it's a background subagent's edit, not the main session's — and checkpointing generally doesn't capture background subagent edits at all (the only exception is a foreground forked skill, which this isn't). So this change is untouched by the rewind regardless of whether it happened before or after the selected checkpoint; the only way to revert it is git.
2. Why build/ stays deleted:
Checkpointing only tracks files modified through Claude's Edit and
Write tools. A file or directory deleted by a Bash command like
rm -rf build/ was never snapshotted as part of any checkpoint,
because checkpointing has no visibility into what a shell command
does to the filesystem — it only observes the specific tool calls it
instruments. There is no checkpoint state to "restore" build/ to.
To get it back, the developer needs either a separate backup, a
rebuild (npm run build or equivalent, if build/ is a build
artifact and not source), or — if build/ happened to be committed
to git at some point, which is unusual for a build output directory
— a git checkout of an earlier commit that still had it.
3. Why /rewind isn't a substitute for committing:
This exact session demonstrates the gap directly: two of the four
changes (the rm -rf and the subagent's lint fix) are completely
outside what /rewind can ever reach, regardless of which checkpoint
is selected, because they were never tracked to begin with. If this
work mattered enough to want a reliable undo path, committing after
prompt 1 and after the subagent's fix would have given the developer
a git revert or git checkout option that covers all four
changes, including the ones checkpointing structurally cannot see.
Checkpoints are a fast, zero-setup, session-scoped safety net for the
specific case of "Claude's own file edits went the wrong direction" —
they are not a general-purpose undo for everything that happened in
the session, and Bash side effects plus subagent edits are exactly
the two biggest holes in that coverage.
Share this question