Checkpointing Your Work in Claude Code: Start Fresh Without Losing Progress

•By Blacdisk Team

Checkpointing Your Work in Claude Code: Start Fresh Without Losing Progress

The fear behind "should I clear this session?" is usually the same: what if I need something from it later. Claude Code has three separate answers to that fear, and they solve different versions of the problem. Checkpoints let you rewind code and conversation inside one session. /branch lets you split off a new session without disturbing the one you're in. Session resume lets you close Claude Code entirely and pick a conversation back up, sometimes days later.

This guide covers all three, when to reach for each, and the specific limits that catch people off guard, like the fact that a shell rm isn't tracked and a background subagent's edits aren't restored by rewind.

Key Takeaways

  • Checkpoints happen automatically. Every prompt you send that starts a turn creates one, with no setup required.
  • /rewind gives you five options: restore code and conversation, restore conversation only, restore code only, or summarize the conversation from or up to a point, without touching files on disk.
  • /branch copies your conversation into a new session and leaves the original untouched, which is the right tool for trying a risky change.
  • Checkpoints don't track everything. Shell commands like rm, mv, and cp, most subagent edits, and changes made outside Claude Code are invisible to rewind. Use git for anything that must be permanently recoverable.

The Three Tools, and When Each One Fits

You want to... Use Because
Undo the last few edits, same session /rewind → Restore code Fast, no new session needed
Free up context but keep the thread /rewind → Summarize from/up to here Keeps files untouched, compresses only the conversation
Try a risky refactor without risking your current path /branch Creates an independent session; original stays exactly as it was
Close Claude Code and come back tomorrow Just quit, then claude --resume or claude --continue Sessions save continuously; nothing extra to do
Recover a session you /clear-ed by mistake /rewind in the same process, or /resume The pre-clear session isn't deleted, just set aside
Hand a session to a different person or machine /export, or a SessionEnd hook reading transcript_path Produces a portable transcript instead of relying on local state

The rest of this guide walks through each row in more depth.

How Checkpoints Work Without You Doing Anything

Claude Code automatically tracks Claude's file edits as you work, capturing the state of your code before each prompt you send that starts a turn. Every prompt that starts a turn creates a new checkpoint, and Claude Code keeps file snapshots for the 100 most recent checkpoints in a session (Claude Code docs: Checkpointing, retrieved 2026-09-23). Checkpoints persist with the conversation, so /rewind still works after you resume a session, not just within the process that created them.

There's no configuration step here. If you're using Claude Code normally, checkpoints already exist for your current session. The only setting worth knowing about is retention: Claude Code deletes a session's file snapshots roughly 30 days after it last saved one, and rewinding to a checkpoint whose snapshots are gone fails with a "No files were restored" error. If you want that window longer, set cleanupPeriodDays in your settings.

Opening the Rewind Menu

Run /rewind, or press Esc twice with an empty prompt input, to open the menu. If your prompt input has text in it, the first double-Esc clears that text instead of opening the menu, and the cleared text goes into your input history, so pressing Up recovers it afterward.

The menu lists each prompt you sent during the session, except ones that joined an already-running turn (see "What Doesn't Get Checkpointed" below). Select a point in that list, then choose an action:

After you choose "Restore conversation" or "Summarize from here," the original prompt from that message is put back in your input field so you can re-send it or edit it first. "Summarize up to here" leaves you at the end of the conversation with an empty input instead.

Guiding a Summary

Both summarize options let you steer what survives. Highlight one with the arrow keys, and where the row reads "add context (optional)," type instructions before pressing Enter. Selecting the option by its number key instead summarizes immediately with no added instructions.

Summarizing never touches files on disk, and the original messages stay in the session transcript, so Claude can still reference the details later even after they're compressed out of the active context. A "Summarized conversation" marker appears in the conversation where the compressed messages used to be.

If your goal is actually to try a different approach rather than compress the current one, the docs point you toward /branch instead, since summarizing keeps you in the same session.

Rewinding Past a /clear

This is the detail that changes how aggressively you can use /clear. If you ran /clear earlier in the same Claude Code process, the /rewind menu shows an extra entry at the top labeled /resume <session-id> (previous session). Selecting it resumes the conversation that was active before the clear ran.

Two conditions bound this: the entry is available only until you exit Claude Code or resume a different session, and it requires Claude Code v2.1.191 or later. On earlier versions, run /resume and pick the previous session from the list instead, which reaches the same conversation through a different path.

In practice, this means /clear is closer to "put this aside" than "delete this," as long as you haven't left the process. That's a meaningfully different mental model than most /clear advice assumes.

Branching to Try Something Without Commitment

Branching creates a copy of the conversation so far and switches you into it, leaving the original intact (Claude Code docs: Manage sessions, retrieved 2026-09-23). It's the tool for a specific moment: you're deep into a session, you want to try a different implementation or a riskier change, and you don't want to gamble your current progress to find out if it works.

From inside a session:

/branch try-streaming-approach

If you skip the name, Claude Code names the new branch after the first prompt in the conversation, including after compaction as of v2.1.198, so a branch made late in a long session still gets a meaningful name rather than a generic one. From the command line, the equivalent is:

claude --continue --fork-session

The confirmation after /branch shows two session IDs: the new branch you're now in, and the original you left. The original stays unchanged on disk and stays in the session picker; return to it with /resume <original-name> or by passing its ID to /resume.

What a Branch Actually Inherits

/branch copies the transcript and switches the running process to write to the copy. That distinction decides what carries over:

State After /branch
Conversation history Copied up to the point you ran /branch
"Allow for this session" permission grants Carried over, since the branch runs in the same process. Forking into a separate process with --fork-session starts without them, and you re-approve there
Background subagents and background Bash commands already running Keep running; their output appears in the new branch, not the original
A connected Remote Control session Follows you into the branch

Once two branches exist, they're independent from that point on. If you resume the same session in two terminals without branching, messages from both interleave into one transcript instead, which is a different and usually confusing outcome. Branch when you want separation; don't just open two terminals on the same session ID.

Closing Claude Code and Coming Back Later

Checkpoints and branches both assume Claude Code is still running, or was running recently in the same machine state. For picking work back up after fully quitting, session resume is the mechanism, and it needs no setup: sessions are saved continuously to local transcript files as you work.

Command What it does
claude --continue Reopens the most recent conversation in the current directory
claude --resume Opens the interactive session picker
claude --resume <name> Resumes a named session directly
/resume Switches to a different conversation from inside an active session

A resumed session restores more than the transcript: the model it was using, the permission mode (with some exceptions covered in the docs), any active goal, and non-expired scheduled tasks. It does not restore configuration flags passed at the original launch, like --mcp-config or --add-dir; pass those again if the session depended on them.

Naming Sessions So You Can Find Them

None of this helps if you can't find the session later. Give sessions descriptive names so they're findable in the picker and resumable by name, especially once you're running more than one task in parallel:

If you don't name a session, Claude Code still generates a short title from your first prompt using a background request, and you can pass that generated title to --resume or /resume the same way you'd pass a name you set yourself. Accepting a plan in plan mode also generates a title based on the plan, which replaces any earlier generated title.

When a Session Has Gone Stale

Resuming isn't always the right move on its own. If a session has been inactive for more than about an hour and is over 100,000 tokens, on a Pro or Max plan Claude Code opens a dialog before your first message, because the prompt cache has expired and the next request processes the full history regardless of what you choose. The dialog offers three paths: run /compact immediately and continue from the summary, load the full conversation unchanged, or resume as-is and stop asking. Which one fits depends on whether the detail the summary would drop still matters to what you're about to do next.

There's a separate staleness problem the dialog doesn't solve: if files have changed since the session last read them, either by you or by another process, a resumed session can reason from outdated file contents and give contradictory advice. Neither /compact nor a plain resume fixes that on its own. When you know files changed underneath a session, say so explicitly in your next message, or start fresh and let Claude re-read the current state.

What Doesn't Get Checkpointed

This is the section worth reading before you rely on rewind for something important. Checkpointing has real limits, and they're not obvious from using the feature casually:

Shell command changes aren't tracked. If Claude runs rm file.txt, mv old.txt new.txt, or cp source.txt dest.txt, those changes can't be undone through rewind. Only edits made through Claude's own file-editing tools are tracked. If you need a file back that a shell command removed, git or a backup is your only path, not /rewind.

Most subagent edits aren't restored. A subagent edits files with the same tools Claude uses directly, but Claude Code usually doesn't capture those edits in your session's checkpoints. Whether rewinding restores them depends on how the subagent ran:

External changes aren't tracked. Checkpointing only tracks files edited within the current session. A manual edit you make outside Claude Code, or an edit from a different concurrent session, isn't captured unless it happens to touch the same files the current session is tracking.

Messages sent mid-turn don't get their own checkpoint. If you queue a message while Claude is working and it joins the currently running turn instead of starting a new one, it appears in the conversation but doesn't create a checkpoint, and /rewind doesn't list it separately. To undo it, rewind to the prompt that started the whole turn, which undoes everything in that turn, including work done before your queued message arrived.

Symlinked and hard-linked files aren't restored. Restoring code skips any tracked path that's a symlink or hard link, with a warning naming how many files were skipped. This matters for dotfile-manager symlinks and files that package managers like pnpm hard-link into place. To undo changes to one of those, ask Claude to reverse the edit directly, or edit it yourself.

None of this replaces version control. Checkpoints are built for quick, session-level recovery. For anything that needs permanent history, branching, or team collaboration, that's what git commits are for.

Handing Work to Someone (or Something) Else

Checkpoints and resume both assume the next person picking up the work is you, in Claude Code, on the same machine. Sometimes it isn't. For that case, there's a separate, lighter-weight path.

Run /export to open a menu that copies the current conversation to your clipboard or saves it as a plain-text file, rendered as readable text. Pass a filename directly to skip the menu.

If you need structured data instead of something to read, the options depend on what's triggering the need:

Transcripts are stored as JSONL under ~/.claude/projects/<project>/<session-id>.jsonl by default, but the entry format is internal and changes between versions, so parsing that file directly is a fragile approach. Use /export or one of the interfaces above instead of reading the raw transcript in a script.

Frequently Asked Questions

If I /clear a session by mistake, is it gone?

Not immediately. If you haven't exited Claude Code or resumed a different session yet, open /rewind and look for the /resume <session-id> (previous session) entry at the top, or run /resume directly and pick the previous session from the list. This requires v2.1.191 or later; check claude --version if you don't see the entry.

What's the actual difference between /branch and /rewind's summarize options?

Summarizing stays in the same session; it compresses part of the conversation to free context while you keep working in the same place. /branch creates a genuinely separate session with its own ID, leaving the original completely untouched. Use summarize when the conversation itself is the thing you want to shrink. Use /branch when you want to try something and might want to come back to the exact state you're in now.

Does rewinding undo a database migration or deployment Claude ran?

No. Checkpointing tracks file edits made through Claude's editing tools. A migration applied to a live database, a deployment, or any other side effect outside the file system isn't something /rewind knows about or can undo. Treat those the same way you would in any workflow: with their own rollback mechanism, not a Claude Code feature.

I resumed a session and Claude is giving advice about files that no longer match. What happened?

The session likely doesn't know the files changed since it last read them. Session resume restores the conversation faithfully, but it doesn't re-scan your codebase for changes made in the meantime, whether by you, by another session, or by an external process. Tell Claude explicitly what changed, or start a fresh session so it reads current file contents from scratch.

Do checkpoints cost extra tokens?

The docs don't describe checkpointing as a token cost; it's a local file-snapshot mechanism, separate from context window usage. Summarizing through /rewind, however, is a summarization request like /compact, so that specific action does use tokens, the same way any compaction does.

Where to Go Next

Try this the next time you're about to make a change you're not fully sure of: run /branch first, make the attempt in the branch, and keep the original session as your fallback. If it works, you're already in the winning branch. If it doesn't, /resume back to the original and nothing was lost. That one habit covers most of what checkpointing is for.

Recap: