Git hygiene with an agent in the loop

Claude Code snapshots your files before each prompt, and /rewind walks back to any of them. It feels like undo, so people treat it as undo and commit less often than they used to.

The documentation is direct about why that is a mistake: checkpoints are "designed for quick, session-level recovery" and are explicitly not a replacement for version control. Five documented holes follow from that, and each one is a case where git is the only thing standing behind you.

What rewind does not restore

Anything a bash command touched. The docs are unambiguous: "Checkpointing does not track files modified by bash commands." Their own example is rm, mv and cp, and those "cannot be undone through rewind." Only direct edits through Claude's file-editing tools are tracked.

This is the big one, because an agent doing real work runs commands constantly. A build step that rewrites generated files, a formatter, a script — all outside the safety net.

Most subagent edits. A subagent edits with the same file tools, but Claude Code "usually doesn't capture those edits in your session's checkpoints." Only a foreground forked skill restores as normal. For anything else, including a background /code-review --fix, the documentation's own advice is to "use git to revert them."

Changes from outside the session. Your own manual edits and edits from other concurrent sessions are normally not captured.

Symlinked and hard-linked paths. Restore skips them and warns Restored the code, but skipped N files. Dotfile managers and pnpm both put files in this category.

Anything older than the retention window. Checkpoints are deleted with their session after 30 days, and only the 100 most recent are kept within a session.

Commit more often, not less

The habit that pays is committing at every point you would be annoyed to lose, which with an agent is more often than when typing by hand — an agent covers more ground per minute, so the interval between "working" and "unrecognisable" is shorter.

A commit before starting an agentic task gives you git diff as the review surface and git checkout . as the undo that has no holes in it. That is worth more than any session-level feature, because it survives the session.

Let it commit, keep the message yours to check

Having Claude commit is fine and saves real friction. Read the message before it lands, because a generated message describes the diff it can see, and the diff is not always the change you meant.

Watch for two specific things. A commit that bundles the fix with unrelated formatting churn is harder to revert cleanly later. And a message asserting that something works is a claim about behaviour, which belongs in test output rather than in a commit message.

Branch before anything speculative

Anthropic's guidance for trying risky approaches is to lean on checkpoints and rewind. That works within a session. For anything you might want to abandon tomorrow, or compare against, a branch does the same job durably and costs one command.

Worktrees go further: separate checkouts let parallel sessions work without colliding, which is the documented answer when you are running more than one agent at a time.

Try this

Ask Claude to make a change that involves a bash command touching files — a formatter run, a generated file, a rename via mv. Then /rewind to before it. Compare git status against what you expected to be reverted.

The gap you find is the thing this page is about, and seeing it once is more convincing than reading about it.

What goes wrong

Treating /rewind as undo. It is session-level recovery with five documented exclusions. Undo has no exclusions.

Long uncommitted stretches. The agent's speed is what makes this expensive. Twenty minutes of unreviewed, uncommitted agent work is a large diff to untangle when one part of it is wrong.

Committing the agent's work without reading the diff. Reviewing the diff is the review. Committing first and reviewing in the pull request means the mistake has already travelled.

Assuming a subagent's edits are covered. They usually are not, and this is exactly when you are least likely to be watching.

How to check it worked

After your next agentic session, run git status and git diff before doing anything else. If you can account for every changed file, your commit rhythm is right. If a file surprises you, that is the one that would have been unrecoverable — and it tells you where the previous commit should have gone.