Error recovery in Claude Code: rewind, reset, and get unstuck

Claude Code recovers from a bad turn with checkpoints: /rewind, or Esc twice on an empty prompt, restores code, conversation, or both to any earlier prompt in the session. Checkpoints track only Claude’s file-editing tools, so shell commands, subagent edits, and external side effects need git and permission rules. Recovery ends when tests and the type checker pass again.

This page is for developers in their first weeks with Claude Code. The situation: Claude refactored your authentication module across six files, and the type checker now reports 23 errors. Claude’s fix introduced three new failures, and its next fix broke a test suite that was green before. You are two iterations into a fix-the-fix spiral, and the code is worse than when you started.

What you’ll walk away with from error recovery

• The exact /rewind options, what each one restores, and what checkpoints never restore.
• A five-step triage routine for fix-the-fix loops, with a copy-paste prompt that stops the edits and finds the root cause.
• A root-cause-first prompt for cascading test failures that fixes one cause at a time and proves each fix with a test run.
• When to use /compact, /clear, /branch, or a new session, and a handoff prompt that rebuilds context after a reset.
• Guard rails that make recovery rare: verification gates, git checkpoints, and permission rules for irreversible commands.

Everything below was checked against Claude Code 2.1.283 (claude --help) and the official checkpointing, sessions, and commands documentation on 2026-09-26, except the passages that name 2026-10-12, which were re-checked that day against Claude Code 2.1.296 and Anthropic’s pages.

How do Claude Code checkpoints work?

Claude Code captures the state of your code before each prompt that starts a turn. It keeps file snapshots for the 100 most recent checkpoints in a session and saves them with the conversation, so /rewind still works after you resume with claude --continue or claude --resume.

To open the rewind menu, run /rewind (aliases /undo and /checkpoint) or press Esc twice while the prompt input is empty. If the input holds text, double Esc clears it instead; press Up afterwards to recall the draft.

The menu lists every prompt you sent in the session. Select one, then choose an action:

Action	Code on disk	Conversation	Use it when
Restore code and conversation	Reverted	Reverted	The whole approach was wrong and you want to re-prompt from that point
Restore conversation	Kept	Reverted	The code is fine but the chat went down a dead end
Restore code	Reverted	Kept	You want Claude to remember what failed while you undo the edits
Summarize from here	Kept	Later messages compressed	A long debugging detour is filling the context
Summarize up to here	Kept	Earlier messages compressed	Early exploration is noise, recent work matters
Never mind	Kept	Kept	You opened the menu by accident

The two code options appear only when that checkpoint has tracked file changes. After you restore the conversation or choose Summarize from here, your original prompt goes back into the input so you can edit and re-send it. To steer a summary, highlight a Summarize option with the arrow keys and type what to keep in the add context (optional) row before you press Enter.

Restore code is the underrated option. Claude keeps the memory of the failed attempt, so your next prompt can say “that approach broke the session tests; try the other one” without re-explaining the task.

What checkpoints never restore

Checkpoints track only the edits Claude makes with its file-editing tools. Rewind does not undo:

• Shell commands. rm, mv, cp, code generators, formatters, and git operations that Claude runs through Bash.
• Most subagent edits. A background subagent, including a background /code-review --fix run, edits outside your checkpoints. Revert those with git.
• External side effects. A dropped table, a pushed branch, a sent email, or a deployed Worker.
• Symlinked and hard-linked files. A restore skips them and reports Restored the code, but skipped N files.
• Your own edits made outside Claude Code, and edits from another concurrent session, unless they touch the same files as the current session.

Snapshots are deleted in a retention sweep, by default about 30 days after the session last saved one. Rewinding to an expired checkpoint can fail with No files were restored. Set cleanupPeriodDays in settings to keep them longer. Checkpoints are session-level undo, not version control: commit anything you want to keep.

Caution

Since v2.1.283 (both release channels on 2026-10-12), auto mode is the starting permission mode for most interactive terminal and VS Code sessions, so a classifier approves many commands that Manual mode would ask you about. For anything a checkpoint cannot undo, add explicit deny or ask rules, such as Bash(git push *) and your deploy and database commands. See Claude Code configuration for the rule syntax and permissions and sandboxing for which commands deserve a rule.

How do you break a fix-the-fix loop?

A fix-the-fix loop is a common failure: each repair introduces a new error, and Claude oscillates between two sides of the same conflict. Continuing to prompt “fix it” makes the loop longer. Follow this order instead.

1. Interrupt. Press Esc once to stop the current turn. Claude keeps the conversation so far.

2. Look at the damage without reading every line. Run /diff to see the uncommitted changes and the per-turn diffs, which tells you which files the loop touched, and run your checks yourself, for example npx tsc --noEmit and npm test, in a second terminal or with the ! prefix.

3. Diagnose without edits. Paste the triage prompt below. It forces root-cause reasoning instead of symptom patching.

4. Decide: repair or rewind. If the diagnosis names one root cause with a small fix, approve it. If it names several causes, or the diff touches files outside the task, rewind with Restore code to the prompt before the change.

5. Retry narrower. Re-prompt with a smaller scope and state which side of the conflict is authoritative.

Copy-paste prompt: stop the loop and find the root cause

Stop. Do not edit any files until I approve a plan.

1. Run `npx tsc --noEmit` and the test suite. Show me the error count
   and the failing test names, grouped by file.
2. For each group, name the root cause, not the symptom, and the
   specific edit you made in this session that introduced it.
3. Tell me which is authoritative in each conflict: the interface or
   the implementation, the test or the code. Explain why.
4. Propose ONE change that fixes the largest group, and predict which
   failures it clears.

If more than two root causes exist, recommend a rewind instead of a repair.

The last line matters. It explicitly allows Claude to recommend throwing the work away, which an agent asked to fix things rarely proposes on its own.

When you retry, name the authoritative side explicitly. Without that, Claude tends to alternate between changing an interface and changing its callers:

Copy-paste prompt: retry with a narrower scope

I rewound your last attempt. Try again with these constraints:

- Change only the session-handling logic in src/lib/auth.ts.
- The exported types in src/lib/auth-types.ts are correct and must not
  change. Make the implementation match them.
- Do not touch any test file. If a test fails, tell me why instead of
  editing the test.
- After each file you edit, run `npx tsc --noEmit` and the auth tests.
  Stop and report if either fails.

The ban on editing tests is deliberate. An agent that may edit tests can make a suite green by weakening assertions, and a green suite then proves nothing. To make that rule mechanical rather than a request, see protecting the oracle.

How do you recover from cascading test failures?

After a refactor, many failing tests often share a few root causes. Fixing them one test at a time produces inconsistent patches across test files. Fix causes in order instead: type errors first, then the test file closest to the change, then the full suite.

Copy-paste prompt: cascading test failures, root cause first

Multiple tests are failing. Before you fix anything:

1. Run the full test suite and capture every failure.
2. Group the failures by shared root cause.
3. Pick the group whose fix would clear the most failures. Show me the
   fix and predict exactly which tests it will turn green.
4. After I approve, apply only that fix, re-run the full suite, and
   compare the result with your prediction.

Repeat one group at a time. If a fix clears fewer tests than you
predicted, stop and explain the gap before continuing.

The prediction step is the verification. When Claude says a fix will clear 12 tests and the suite shows 12 fewer failures, you have evidence the diagnosis was right without reading the patch. A mismatch tells you the root-cause model is wrong, which is exactly when to stop. For the full hypothesis-to-regression-test loop, see debugging with Claude Code.

When should you use /compact, /clear, or a new session?

Long sessions accumulate file reads, command output, and abandoned attempts. When Claude starts forgetting project conventions or repeats a mistake you already corrected, the useful context is buried. Pick the lightest tool that fixes it:

Symptom	Tool	What happens
One long detour is filling the context	/rewind → Summarize from here	Compresses only that stretch; earlier instructions stay intact
The whole session is long but still on task	/compact focus on the auth refactor and the two failing tests	Summarizes the conversation; the focus text tells Claude what to keep
Claude keeps returning to an approach you rejected	/clear	Starts an empty conversation in the same process
You want to try an alternative and keep the current path	/branch try-token-rotation or claude --continue --fork-session	Copies the conversation into a new session; the original stays unchanged
The task is done and the next one is unrelated	Exit and run claude	A new session with nothing carried over

Two details make /clear safer than it looks. /clear auth-attempt-1 labels the old conversation in the /resume picker. And in the same process, the rewind menu shows a /resume <session-id> (previous session) entry at the top, so a mistaken /clear is reversible. Run /context to see how full the window is before you decide.

After /clear or in a new session, rebuild context from files, not from memory:

Copy-paste prompt: rebuild context after /clear

We are resuming an auth refactor. Do not edit anything yet.

Read @src/lib/auth.ts, @src/lib/auth.test.ts, and
@src/api/routes/login.ts, then run `git diff main --stat` and the
auth tests.

State of play: session handling is now async; the type checker passes;
two tests in auth.test.ts fail on mock setup for the async functions.
Rejected approach: restructuring the module into classes. Do not
propose it again.

Tell me: what the current code does, why the two tests fail, and the
smallest fix. Wait for my approval.

Stating the rejected approach is what stops a fresh session from walking into the same dead end. If a fact must survive every reset, such as “the exported auth types are frozen”, put it in CLAUDE.md instead; see the memory system.

How do you get back to an earlier session?

Command	Where	What it does
claude --continue (-c)	Terminal	Reopens the most recent conversation in the current directory, including its checkpoints
claude --resume (-r)	Terminal	Opens the session picker
claude --resume auth-refactor	Terminal	Resumes a named session directly
/resume	Inside a session	Switches to another conversation
claude -n auth-refactor or /rename auth-refactor	Terminal or session	Names a session so you can find it later

In the picker, Ctrl+B filters to sessions from the current git branch, Ctrl+W widens to all worktrees of the repository, Ctrl+A widens to every project, and Space previews a session. Sessions started with claude -p do not appear in the picker or in --continue; resume them with claude --resume <session-id>.

When you resume, pass launch flags such as --mcp-config, --settings, --plugin-dir, --fallback-model, or --add-dir again. Claude Code does not restore them, and a session that loses its MCP server fails in confusing ways.

How do you prevent the next recovery?

Recovery is cheap when the failure is caught one edit after it happens. These habits keep it that way.

Make verification automatic, not a request. A prompt that says “run the tests after each change” works until the context is compacted. A PostToolUse hook that runs the type checker after every edit, or a Stop hook that runs the test suite before Claude reports done, keeps working. See hooks automation. The gate, not your reading, is what tells you the change is correct: you sign off on a green type check and test run plus a /diff that stays inside the task’s files, not on a line-by-line read.

Commit a git checkpoint before risky work. Checkpoints cover Claude’s edits; git covers everything else, including your own changes and shell-command output. Commit, or ask Claude to, before a broad refactor. If the attempt fails, git restore --staged --worktree . discards changes to tracked files and git clean -n lists the new untracked files Claude created (git clean -f deletes them). Both discard work, so run git status first. See version control with Claude Code.

Plan before a multi-file change. Press Shift+Tab to reach plan mode, or run /plan, and approve a file-by-file plan before any edit. Rejecting a bad plan costs one message; reverting a bad implementation costs a rewind and a retry.

Narrow the scope. “Change only the session-expiry logic in auth.ts” touches one file and fails in one place. “Refactor authentication” touches everything and fails everywhere.

What breaks when you try to recover?

The rewind menu does not show the checkpoint you want. You are probably in a different session. The menu lists only the current session’s prompts. Resume the original with claude --resume and open /rewind there. A message you queued while Claude was working joins that turn and gets no checkpoint of its own; rewind to the prompt that started the turn.

Rewind reports No files were restored. The backups for that checkpoint are gone (the retention sweep deletes them about 30 days after the session last saved one), or Claude Code could not write to or delete the files. Revert with git, and raise cleanupPeriodDays if you often return to old sessions.

Files are still wrong after Restore code. Claude changed them through Bash, a formatter, a code generator, or a background subagent, and checkpoints do not track those edits. Run git status to find them and git restore them. A symlinked or hard-linked file is skipped with Restored the code, but skipped N files; ask Claude to reverse that edit or fix the file yourself.

Claude repeats the approach you rewound. Restore code and conversation also removes the memory of why the approach failed. Use Restore code instead, or state the rejected approach in your next prompt.

/compact dropped a detail you needed. Run /compact with a focus argument naming the files, errors, and decisions to keep. Anything that must survive every compaction belongs in CLAUDE.md.

Tests pass, but you suspect a subtle bug. A passing suite proves only what it asserts. Run /code-review on the change, then ask Claude to write a failing test for the edge case you suspect before it fixes anything. See testing with Claude Code.

The session is too degraded to steer. Stop fighting it. Exit, start claude, and use the rebuild-context prompt. A fresh session with three files and a two-line summary is easier to steer than a long session full of abandoned attempts.

Where to go next after error recovery

This page closes the Claude Code quick start. For stuck sessions caused by installation, authentication, or network problems rather than bad edits, see Claude Code troubleshooting. Recovery works differently in the other tools: see Codex error recovery and Cursor error handling.

Debugging with Claude Code From hypothesis to regression test, without guessing

Hooks automation Turn type checks and tests into gates that run on every edit

Version control Commits, branches, and worktrees as your second safety net

Context windows Why long sessions degrade and how to budget context