Get the free coreGet core

Claude Code checkpoints: what they save and what they miss

Updated 5 min readSection 04 / Incidents & recovery
SHORT ANSWER

A Claude Code checkpoint is a saved point in your session that you can go back to. Claude Code automatically tracks Claude's file edits, and you return to a checkpoint with /rewind or /undo. Manual edits made outside Claude Code are normally not captured. Snapshots are kept for the 100 most recent checkpoints and swept about 30 days after a session last saved one.

This page separates three things: what Claude Code saves, what it can restore, and how long that lasts. If you only want the steps to undo, go to Claude Code undo.

01What a Claude Code checkpoint is

A checkpoint is a point you can go back to. Claude Code creates one with each prompt you send that starts a turn. What it records is Claude's file edits, the ones made with its file editing tools. A file editing tool is the part of Claude Code that writes to a file directly, as opposed to a shell command that happens to change one.

You open the list with /rewind, or its alias /undo. Press Esc twice with an empty prompt input and you get the same menu. For the three restore choices in that menu, see Claude Code undo.

02What is tracked and what is not

CaseTracked by checkpoints?
Edits Claude makes with its file editing toolsYes
A file changed only by Bash commandsNo, it stays as it is; use Git
Manual changes you make outside Claude CodeNormally not captured
Edits from other concurrent sessionsNormally not captured
Subagent editsUsually not captured
Older checkpoints in a long sessionFile snapshots exist only for the 100 most recent

The second row decides most surprises. A bulk delete that Claude runs as a shell command goes through Bash, so if Claude never edited those files with its tools, they are not in a checkpoint and rewind will not bring them back. The deleted files guide covers that case.

03How long checkpoints stay

There are two limits. Inside one session, Claude Code keeps file snapshots for the 100 most recent checkpoints. Across sessions, it deletes a session's file snapshots in a retention sweep, which is an automatic cleanup of old snapshots, by default about 30 days after the session last saved one.

Checkpoints are saved with the conversation, so /rewind still works after you resume a session. Resuming has its own clock: Claude Code stores session transcripts locally in plaintext under ~/.claude/projects/ for 30 days by default. A version you may need next quarter does not belong in a checkpoint, because snapshots are cleaned up by count and by age. Commit it to Git instead.

04Git covers what checkpoints miss

For a file Bash commands changed, the docs say to use version control such as Git. Git keeps its own record of your project, so it works when Claude Code never saw the change.

Two Git words. The working tree is the files in your project folder as you see them. The index, or staging area, is the list of changes you have added for the next commit.

Warning: this command replaces the file in your working tree. git restore <file> gets a deleted tracked file back from the index, and edits to that file that you had not staged are replaced:

git restore <file>

If you plan to move a branch back with git reset --hard, know that it overwrites all files and directories with the version from the commit, and may overwrite untracked files, which are files Git has never tracked. Save the current state first; the safe order is on undo a Git reset. More recipes: restore a deleted file in Git. Files that were never committed are covered on restore untracked files.

A Cursor forum reply gives the same habit for Cursor: committing before an agent session is the most reliable way to roll back. That is a forum reply, not a product guarantee.

05Other layers on a Mac

Checkpoints are one layer among several, and each layer has a different job. Time Machine local snapshots are a separate layer from Claude Code, and they can recover previous versions of files even if your backup disk is not attached. The steps are on restore from Time Machine. Cursor keeps its own checkpoints, stored locally and separate from Git, with limits of their own; see Cursor restore checkpoint.

06A worked example

Say Claude edits two files with its file editing tools, then runs a shell script that deletes a third file you never asked it to touch. Each prompt made a checkpoint, and the two edits are tracked. Rewind can put those two files back. The third file only changed through Bash and was never edited with Claude's tools, so it isn't tracked and stays as it is. If that file was committed, Git still has it; if it was never added to Git, look at restore untracked files.

So before you rely on rewind, ask one question: did the change I want to undo come from Claude's file editing tools, or from something else, such as a script, a subagent or my own hands? Only the first kind is the checkpoint's job. For the rest, a commit made before the session is your copy.

Auto mode adds one more layer for risky Git commands. Its classifier, the check that screens each action, presumes that git reset --hard and similar commands would discard uncommitted changes. The auto mode page lists what it blocks.

07Claude Code checkpoint: what to remember

A Claude Code checkpoint covers Claude's file edits. It lasts for 100 checkpoints in a session and about 30 days after the last save. Commit before long sessions.

Checkpoints undo edits after the fact. Checkpoints miss what Bash commands changed; Artificial Immunity's free, open-source core watches Claude Code sessions and program starts on your Mac and reports what it finds, without stopping anything.

FAQ

What does a Claude Code checkpoint save?

Claude Code automatically tracks Claude's file edits as you work. Each prompt you send that starts a turn creates a checkpoint. To undo the edits, run /rewind or its alias /undo.

Does a checkpoint cover files that Bash commands changed?

Not when only Bash commands changed the file: such a file isn't tracked and stays as it is. To revert it, use version control such as Git.

How many checkpoints does Claude Code keep?

Claude Code keeps file snapshots for the 100 most recent checkpoints in a session.

How long are checkpoints kept?

Claude Code deletes a session's file snapshots in the retention sweep, by default about 30 days after the session last saved one. Checkpoints are saved with the conversation, so /rewind still works after you resume a session.

Does a checkpoint cover edits made by a subagent?

Usually not. Claude Code usually doesn't capture subagent edits in your session's checkpoints. A subagent is a helper that Claude starts for a side task.

Can I rewind after I resume a session?

Yes. Claude Code saves checkpoints with the conversation, so you can still run /rewind after you resume a session.

Sources

  1. Claude Code docs, checkpointing
  2. Cursor docs, agent overview
  3. Cursor forum, restore checkpoint reply
  4. Apple Support, back up with Time Machine
  5. Artificial Immunity
Relying on checkpoints? Artificial Immunity watches the Mac where your agents work.Get the free core