Sessions & Checkpointing

A session is a saved conversation tied to a project directory, stored locally as you work. Checkpoints snapshot your code before each change so you can rewind.

Resume Sessions

Command	What it does
claude --continue (-c)	Resume most recent session in current directory
claude --resume (-r)	Open the interactive session picker
claude --resume <name>	Resume a named session directly
claude --from-pr <number>	Resume the session linked to that PR
/resume	Switch conversations from inside a session

Sessions from claude -p / Agent SDK don’t appear in the picker but can be resumed by session ID (from the same directory).

Name Your Sessions

Names make sessions findable and resumable — critical when running parallel work.

When	How
At startup	claude -n auth-refactor
During session	/rename auth-refactor
In session picker	Highlight + Ctrl+R
On plan accept	Auto-named from plan content

Session Picker Shortcuts

/resume or claude --resume opens the picker:

Key	Action
↑/↓, Enter	Navigate, resume
Space	Preview session content
Ctrl+R	Rename
typing / paste PR URL	Search (finds session that created a PR)
Ctrl+W	Widen to all worktrees of repo
Ctrl+A	Widen to all projects on machine
Ctrl+B	Filter to current git branch

Branch a Session (fork)

Try a different approach without losing the current path:

/branch try-streaming-approach

or from the shell:

claude --continue --fork-session

Original stays intact in the picker. Forks group under their root session (expand with →).

Checkpointing & /rewind

Every user prompt creates a checkpoint of files Claude edits. Persists across sessions, cleaned up after 30 days (cleanupPeriodDays).

Open the rewind menu with /rewind or double-Esc (with empty input). Per prompt you can:

• Restore code and conversation — full revert to that point
• Restore conversation — rewind chat, keep current code
• Restore code — revert files, keep chat
• Summarize from here — compress everything after that point (free context)
• Summarize up to here — compress everything before it

Limitations — know these!

• Bash-made changes are NOT tracked (rm, mv, cp, script output)
• External/manual edits are not tracked
• Not a replacement for git: checkpoints = local undo, git = permanent history

Manage Context Within a Session

Command	Effect
/clear	Fresh empty context (old conversation stays resumable)
/compact [instructions]	Replace history with a summary
/context	Show what’s consuming context right now

Export & Transcripts

• /export — copy conversation to clipboard or save as text file
• Transcripts: ~/.claude/projects/<project>/<session-id>.jsonl (format is internal — script against /export or claude -p --output-format json instead)
• Scripted follow-up to an existing session:

claude -p --resume <session-id> --output-format json "summarize what we changed" | jq -r '.result'

Real Case: Recovering From a Bad Refactor

1. "refactor payment module to strategy pattern"   → 12 files changed
2. Tests fail badly; approach was wrong
3. Double-Esc → select the refactor prompt → "Restore code and conversation"
4. Code is back; prompt is restored in the input box — edit it and try again

Zero git surgery needed.

🧠 Quick Recall

• Trick: “Name it to find it.” -c = latest here, -r = pick.
• “/branch to fork, Esc-Esc to rewind.”

👨‍🏫 Teach It

• Show: the wreck-and-rewind demo — deliberately bad refactor, then restore.
• They’ll trip on: bash changes are NOT checkpointed — rm can’t be rewound.

---

Learning path: ⬅ 07-tools-deep-dive.md · Index · ➡ 09-context-window-management.md