Sessions, Checkpoints & Rewind

Two recovery systems run side by side in Claude Code, and mixing them up causes most of the confusion in this area. Hold them apart from the start.

A session is a saved conversation tied to a project directory. Claude Code streams it to a local transcript file as you work, so you can exit, come back, and pick up exactly where you left off — or branch off to try a different approach. Sessions are the coarse unit: whole conversations you resume, fork, name, and export.

A checkpoint is a fine-grained snapshot taken inside a session, automatically, before Claude edits files. It is your in-session undo button. Every prompt you send creates one, so you can rewind to any earlier point and restore the code, the conversation, or both.

SESSION  (one conversation, tied to a directory)
  ├─ checkpoint @ prompt 1   ← every user prompt snapshots Claude's edits
  ├─ checkpoint @ prompt 2
  ├─ checkpoint @ prompt 3   ← Esc Esc / /rewind to jump back here
  └─ ...

The key distinction: you resume a session (across time, across restarts) but you rewind within one using checkpoints. Sessions live in ~/.claude/projects/; checkpoints live attached to a session and clean up with it.

Because every session is saved continuously, you can return to one after exiting or even after running /clear. There are three entry points from the command line plus one from inside a session.

You can also continue non-interactively — useful in scripts: claude -c -p "<query>" continues the previous session and prints the answer.

Name resolution is smart but exact. With claude --resume <name>, an exact match resumes directly; an ambiguous name opens the picker with that name pre-filled as a search term. With /resume <name>, an exact match resumes directly, but an ambiguous name reports an error — run /resume with no argument to open the picker instead.

Run /resume inside a session, or claude --resume with no arguments, to open the interactive picker. By default it shows interactive sessions from the current worktree, plus sessions started elsewhere that added the current directory with /add-dir. Each row shows the session name (or its summary / first prompt), time since last activity, message count, and git branch.

These keys drive it:

Forked sessions created with /branch, /rewind, or --fork-session are grouped under their root session — press → to expand the group. Since v2.1.144, background sessions are marked in the picker so you can tell detached agents apart from interactive ones.

Sometimes you want to explore a different path without abandoning the one you're on. Branching copies the conversation so far and switches you into the copy, leaving the original untouched.

From inside a session, run /branch with an optional name (alias /fork):

/branch try-streaming-approach

From the command line, combine --continue or --resume with --fork-session — this assigns a new session ID instead of reusing the original:

claude --continue --fork-session
claude --resume abc123 --fork-session

The original is unchanged and stays in the picker. The /branch confirmation prints two session IDs — the new branch you're now in and the original — so you can jump back with /resume <id>, the picker, or /resume <original-name>.

Two gotchas worth internalizing: permissions you approved with "allow for this session" do not carry over to a new branch. And if you resume the same session in two terminals without forking, messages from both interleave into one transcript — fork if you want isolation.

Export and share with /export [filename] (copies the conversation to clipboard, or writes a readable plain-text file if you pass a name) and /copy [N] (copies the Nth-latest response; offers a picker for individual code blocks, with w to write to a file).

Checkpoints are created automatically — every user prompt snapshots the state of your code before Claude's edits, and checkpoints persist across sessions so you can reach them in resumed conversations.

To time-travel, run /rewind (aliases /checkpoint, /undo) or press Esc twice when the prompt input is empty. If the input has text, double-Esc clears it instead (the cleared text is saved to input history — press Up to recall it after).

The menu lists each prompt you sent. Select a point, then choose an action. The crucial split is restore (reverts state) vs. summarize (compresses context, changes no files):

Restore options undo state. Summarize options compress part of the conversation into an AI-generated summary without touching files on disk — like a targeted /compact where you pick which side of the message to shrink. In both summarize cases the original messages stay in the transcript, so Claude can still reference details, and you can type optional instructions to steer the summary.

Checkpoints are powerful but have hard edges. Know them before you rely on them.

They track Claude's file-edit tools ONLY. If Claude runs a shell command that changes files — rm file.txt, mv old.txt new.txt, cp source.txt dest.txt, or a git reset — those changes cannot be undone through rewind. Only direct edits via Claude's file-editing tools are snapshotted.

They don't see external changes. Manual edits you make outside Claude Code, or edits from another concurrent session, normally aren't captured unless they happen to touch the same files this session edited.

They are separate from git and not a replacement for it. Think of checkpoints as local undo and git as permanent history. Keep committing for real version control, branches, and collaboration.

Cleanup. Checkpoints are cleaned up along with their session after 30 days by default (configurable via cleanupPeriodDays).

Now the directory point. Sessions tie to a project directory, not a git branch. A session is keyed by your working directory path, and the transcript is just a conversation — it does not snapshot your whole working tree. So if you switch git branches while a session is open (or before resuming one), the files on disk change underneath Claude. The same session can see entirely different code depending on the branch you're standing on. This is why git worktrees are the clean way to run parallel sessions on different branches: each worktree is its own directory, so each gets its own session scope with no branch-switching surprises.

Transcripts are stored as JSONL at ~/.claude/projects/<project>/<session-id>.jsonl, where <project> is derived from your working directory path — one line per message, tool use, or metadata entry. (Point CLAUDE_CONFIG_DIR elsewhere to relocate the whole store.)

Because sessions never intentionally expire on their own and accumulate as you work, ~/.claude/projects/ can balloon to gigabytes over time — long debugging runs and pasted screenshots (stored at full resolution in the JSONL) are the worst offenders. Two cleanup mechanisms keep it in check:

• Automatic time-based cleanup. Local transcript files (and their checkpoints) are removed after 30 days by default. Change the window with the cleanupPeriodDays setting.
• Explicit purge. claude project purge [path] deletes local Claude state on demand; use --dry-run to preview, -y to skip the prompt, or --all to clean everywhere.

If you want to avoid writing transcripts at all, set CLAUDE_CODE_SKIP_PROMPT_HISTORY, or in non-interactive mode pass --no-session-persistence.