Claude Code Checkpoints and Rewind: The Undo Button You Actually Need

Claude Code checkpoints are automatic snapshots of your working files that Claude Code takes right before it edits anything, so you can rewind to an earlier state without touching git. If an agent run goes sideways, mangles a file, or takes a refactor in the wrong direction, you press Escape twice (or run /rewind), pick a point in time, and your code (and optionally the conversation) jumps back to it. No staged commits, no git stash, no cleanup script. This article walks through what checkpoints actually capture, how the rewind flow works step by step, where it fits next to git, and how to build a workflow that uses both without fighting either.

If you have ever watched an agent confidently "fix" a bug by deleting half a file, you already know why this feature exists. Checkpoints exist for the fifteen seconds between "that doesn't look right" and "let me just revert."

What Claude Code Checkpoints Actually Capture

A checkpoint is a snapshot of the files in your working directory taken at a specific moment in a session, paired with the state of the conversation at that same moment. Claude Code creates one automatically right before it performs a file-modifying action: an Edit, a Write, a NotebookEdit, or a multi-file refactor tool call. You do not have to ask for it and you do not have to remember to save anything.

Each checkpoint stores two things independently:

• Code state: the contents of every file Claude is about to touch, captured just before the edit lands.
• Conversation state: the message history up to that point, including your prompts and Claude's responses.

Because these two are tracked separately, rewind gives you three choices when you jump back: restore the code only, restore the conversation only, or restore both together. That separation matters more than it sounds. Sometimes the code Claude wrote was fine but the conversation went down a confusing rabbit hole you want to prune. Other times the conversation is worth keeping (you want Claude to remember why it made a decision) but the actual file changes need to be undone.

Checkpoints are scoped to a session and stored locally on disk, not in your git history and not on any server. They are not commits. They do not show up in git log, they are not pushed anywhere, and closing your terminal or clearing a session removes them. Think of checkpoints as an undo stack for an agent session, the same category of feature as "undo history" in a text editor, just extended to cover multiple files and the reasoning that produced them.

How to Trigger a Rewind

There are two ways to open the rewind picker in Claude Code:

1. Double-tap Escape. Press Esc twice in quick succession during or after a session. This opens a list of recent checkpoints, most recent first, each labeled with a short summary of what changed and roughly when.
2. Run the slash command directly. Type /rewind and hit enter.

Both routes land you on the same picker. From there:

> /rewind

Select a checkpoint to restore:

  1. Just now      Edited src/routes/checkout.ts, src/lib/tax.ts
  2. 2 min ago      Ran Edit on src/lib/tax.ts (added GST rounding)
  3. 6 min ago      Wrote tests/tax.test.ts
  4. 9 min ago      Session start

Pick a checkpoint with the arrow keys and enter, and you are prompted for what to restore:

Restore checkpoint from 2 min ago:

  [1] Code only
  [2] Conversation only
  [3] Code and conversation

Choosing "code only" reverts every file Claude touched since that checkpoint to exactly how it looked at that moment, while leaving the conversation transcript intact so Claude still remembers what it tried and why it did not work. This is the option to reach for when you want to say "keep the context, undo the mess" and immediately ask for a different approach.

Choosing "conversation only" rolls the chat back without touching your files. Use this when the code Claude produced is actually correct, but the conversation got cluttered with a wrong turn (a misdiagnosed bug, a tangent about the wrong file) and you want a cleaner context window going forward, without losing the working code.

Choosing "code and conversation" is the full rewind: both go back together, as if that later part of the session never happened. This is the closest thing to git reset --hard plus deleting chat history, scoped to the session.

After you restore, Claude Code confirms what changed:

Restored 2 files to checkpoint from 2 min ago.
Conversation kept at current state.

You can rewind multiple times in a row, including forward and backward between checkpoints, as long as the session is still open. Nothing is destroyed permanently until you start a fresh session or the checkpoint history ages out.

Why Checkpoints Exist: The Problem With Agentic Edits

Before checkpoints, the safety net for an agent making file changes was whatever version control discipline you brought to the session yourself. That works fine if you commit before every prompt, but in practice almost nobody does that consistently, especially during fast iterative loops where you are firing off five or six prompts in a row to shape a feature.

The failure mode checkpoints solve is specific: an agent makes a multi-file change, you notice something is wrong two or three prompts later, and by then the "good" state is buried under several edits across files you were not watching closely. Reconstructing that state by hand, or worse, by asking the agent to "undo what you just did," is unreliable. The agent's own memory of exactly what it changed degrades the same way yours does.

Checkpoints remove the reconstruction step entirely. Instead of asking Claude to reverse-engineer its own diff, you point at a moment in time and say "that one, exactly." The snapshot is literal, not reasoned about, so there is no room for the rewind itself to introduce a new bug.

This is also why checkpoints are automatic rather than opt-in. A feature you have to remember to invoke before every risky prompt gets skipped exactly when you need it most, which is when you were not expecting the edit to go wrong.

Claude Code Checkpoints Versus Git Commits

It is tempting to treat checkpoints as a replacement for git discipline. Do not. They solve different problems and operate on different timescales.

Checkpoints are:

• Automatic, created on every file-modifying tool call
• Local to the current session, gone when the session ends
• Fast to create and fast to restore, no message required
• Aware of conversation state, not just file state
• Not visible to teammates, not pushed, not part of your project history

Git commits are:

• Manual (or CI-triggered), created when you decide there is something worth recording
• Permanent project history, shared across the team once pushed
• Require a message that explains intent for future readers
• Blind to any conversation that produced the change
• The actual audit trail for code review, blame, and releases

The practical pattern is to let checkpoints handle the messy middle of a session, the false starts and half-finished refactors, and let git handle the meaningful boundaries: "tests pass," "feature works," "ready for review." Rewind gets you back to a good spot inside a session. Git gets you back to a good spot across days, branches, and collaborators.

A workflow that uses both looks like this in practice:

# Start clean
git status
git add -A && git commit -m "checkpoint before agent session: rate limiter"

# Work with Claude Code, let it edit freely
# Use Esc Esc / rewind liberally as you iterate

# Once the feature actually works
git diff --stat
git add -A && git commit -m "add sliding-window rate limiter to auth middleware"

Commit before you hand the agent something risky, work inside that boundary using rewind as your safety net, and commit again once you have something worth keeping. You are never more than a rewind away from the last good in-session state, and never more than a git reset away from the last good project state.

Setting Up a Workflow Around Rewind

A few habits make checkpoints noticeably more useful, especially on larger sessions where dozens of checkpoints accumulate.

Prompt in small, reviewable increments. Checkpoints are created per edit, so the more granular your prompts, the more precise your rewind points. Asking for "refactor the entire auth module" in one shot gives you one giant checkpoint to either keep or discard. Asking for it in three or four smaller prompts, each touching a narrower slice, gives you three or four rewind points, so a bad step three does not force you to discard good steps one and two.

Check the diff before you keep moving forward. After any agent edit, a quick git diff (even before committing) tells you whether the checkpoint you are about to build on top of is actually sound:

git diff --stat
git diff src/lib/tax.ts

If something looks off, that is the moment to rewind, not three prompts later.

Use "code only" restores when you want to redirect, not restart. If Claude tried an approach and got it wrong, restoring code only while keeping the conversation means your next prompt can say "that approach with the recursive walk was too slow, try an iterative one instead" and Claude has full context for why the first attempt failed. That produces a better second attempt than starting the conversation over.

Reach for "conversation only" restores when the context window is the problem, not the code. Long debugging sessions accumulate a lot of dead-end reasoning in the transcript. If the current file state is good but the conversation is bloated with wrong theories, a conversation-only rewind cleans the mental slate for future turns while keeping the working code exactly as it is.

Do not rely on checkpoints across a closed terminal. They are session-scoped. If you need something to survive a restart, a crashed terminal, or a machine reboot, that is what git is for. Commit before ending a session if the in-progress state matters.

A Worked Example: Recovering From a Bad Refactor

Here is a concrete sequence showing checkpoints doing their job.

> Refactor the pricing calculator to support multi-currency

Claude edits src/lib/pricing.ts and src/lib/currency.ts. You run the tests.

npm test -- pricing

Three tests fail. You look at the diff and realize Claude changed the rounding behavior for INR in a way that breaks existing invoices. Rather than prompting "please undo that" and hoping the agent's next edit precisely reverses the first one, you rewind:

Esc Esc

Select a checkpoint to restore:
  1. Just now   Edited src/lib/pricing.ts, src/lib/currency.ts
  2. 4 min ago  Session start

> 1

Restore checkpoint from just now:
  [1] Code only
  [2] Conversation only
  [3] Code and conversation

> 1

Files revert to their pre-refactor state, exactly. The conversation still has your original request and Claude's attempt, so your next prompt can be specific:

> The multi-currency refactor broke INR rounding, existing invoices rely on
> round-half-up at 2 decimals. Redo the refactor but keep that rounding
> rule unchanged for INR specifically.

Claude now has both the goal and the failure mode in context, and produces a second attempt that is far more likely to be correct on the first try, because it is not guessing at what went wrong. That is the actual value of checkpoints: not just undo, but undo that preserves the reasoning trail so the next attempt is informed rather than blind.

Common Pitfalls

Treating checkpoints as a backup strategy. They are not persisted outside the session and are not a substitute for source control. If you would be upset to lose it permanently, commit it.

Rewinding too late. The longer you wait after a bad edit, the more checkpoints pile up between "good" and "now," and the harder it is to identify exactly which one you want. Rewind as soon as you notice something is wrong, not after three more prompts building on top of it.

Forgetting that rewind affects files on disk immediately. A code restore is not a preview, it actually rewrites the files in your working directory the moment you confirm it. If you have unsaved changes made outside of Claude Code (manual edits in your editor) that are not reflected in a checkpoint, those changes can be overwritten. Save or commit manual edits before triggering a rewind.

Assuming rewind fixes logic errors the same way it fixes bad edits. Rewind is a mechanical restore of prior state, it has no opinion about whether the code you are restoring to was actually correct. If checkpoint 3 was already broken in a subtler way, rewinding to it just moves you to a different broken state. Pair rewind with actually running your tests at each checkpoint, not just visually inspecting the diff.

FAQ

Do Claude Code checkpoints replace the need for git? No. Checkpoints handle undo within a single session and disappear when the session ends. Git is your permanent, shareable project history. Use checkpoints for fast in-session recovery and keep committing at meaningful milestones.

What triggers a new checkpoint? Any file-modifying tool call, such as an edit, a full file write, or a notebook edit, creates a checkpoint immediately before the change is applied. Read-only actions like searching or running tests do not create checkpoints, since there is nothing to revert.

Can I rewind the conversation without touching my files? Yes. When you open the rewind picker with Esc Esc or /rewind and select a checkpoint, you are asked whether to restore code only, conversation only, or both. Conversation-only restores leave every file exactly as it currently is.

What happens to checkpoints after I close the session? They are session-scoped and do not persist once the session ends. If you need to preserve a state permanently, commit it with git before closing out.

Can I rewind forward again after going back? Yes, as long as the session is still active. The checkpoint list keeps every snapshot taken during the session, so you can move between them in either direction until you start a new session.

Does rewinding to a code-only checkpoint discard manual edits I made outside Claude Code? It can. A code restore rewrites the files on disk to match the snapshot, so any manual changes made after that checkpoint that were not saved through Claude Code can be lost. Save or commit manual edits first if you want to keep them.

Is there a limit to how many checkpoints a session can hold? Checkpoints accumulate for the life of the session and are pruned when the session ends, rather than being capped at a fixed small number during active use. In very long sessions, use the picker's timestamps and short descriptions to find the right one rather than scrolling blindly.

Do checkpoints work the same way across different projects? Yes, the behavior is tied to Claude Code itself, not to a specific repository or language. Any project you run Claude Code in gets the same automatic snapshotting and the same Esc Esc / /rewind flow.