Claude Code Resume: Continue, Name and Branch Sessions

To pick up a Claude Code task where you left off, run claude --continue for the most recent session in the current directory, or claude --resume to choose from a list. Name a session when you start it (claude -n auth-refactor) and you can return to it later with claude --resume auth-refactor. The cost deserves attention: resuming sends the whole conversation again, so a long session that has gone cold is not free.

This guide covers the commands, what a resumed session does and does not restore, how to branch a session, and when starting fresh is the better choice.

How do I resume a Claude Code session?

Claude Code saves each conversation locally as you work, tied to a project directory. You can come back after exiting or after running /clear. These are the entry points, from the session docs:

claude -c is the short form of --continue. If there is no session in the directory yet, --continue prints No conversation found to continue and exits.

You can also resume by session ID from any directory. Claude Code looks in the current project and its git worktrees first, then in every other project on the machine.

# latest session here
claude --continue

# pick from a list
claude --resume

# jump straight to a named one
claude --resume auth-refactor

Find the session behind a pull request

When Claude creates a PR with gh pr create or glab mr create, Claude Code links the session to it. Later, claude --from-pr 1234 (use your own number) opens the picker filtered to that PR. You can also paste a GitHub, GitHub Enterprise, GitLab or Bitbucket pull or merge request URL into the picker's search. This is the quickest route back when a reviewer asks for a change on a PR from last week.

How do I name sessions?

Names make parallel work manageable. Set one in any of these ways:

Once a session has a name, claude --resume <name> and /resume <name> both find it.

Sessions you never name still get two labels. The default display name, something like my-app-3f (the directory name plus a two-character suffix), identifies the session in listings of running sessions. It is not a resume handle: passing it to --resume will not find the session. The second label is a generated title, a short summary of your first prompt, and that one does work with --resume. A claude -p run started directly from a shell or script does not get a generated title.

If a name matches more than one session, claude --resume <name> opens the picker with the name pre-filled as a search. Inside a session, /resume <name> reports an error in that case; run /resume alone to get the picker.

Picker shortcuts worth knowing

Run claude --resume or /resume to open the picker:

• Space previews a session.
• 1 to 9 resumes the session at that position in the list.
• Ctrl+W widens the list to all worktrees of the repository (shown only in multi-worktree repositories); Ctrl+A widens it to every project on the machine.
• Ctrl+B filters to the current git branch.

By default the picker shows sessions from the current worktree. Resuming by name works across the current repository and its worktrees, so parallel sessions in worktrees are still reachable by name.

What does a resumed session restore?

The conversation history, including tool calls and results. If the session was compacted, it opens at a Conversation compacted row and continues from the last summary plus the messages since. Also restored:

• Model: the session continues on the model it was using, with a few exceptions listed in the model configuration docs.
• Agent: a session started with --agent continues as that agent.
• Permission mode: restored when you resume from a terminal with --continue, --resume <session-id> or --resume <name> (when the name matches one session), without -p. Pass --permission-mode to override it.
• Active goal and unexpired session-scoped scheduled tasks.

Two details about permissions. A session that ended in bypassPermissions does not resume in it; you must enable it again at launch. And a session that ended in plan mode resumes in plan mode when you resume from a terminal, except with --fork-session or when a deny rule removes the ExitPlanMode tool.

What you must pass again

Not every launch flag survives. If the session depended on --mcp-config, --settings, --plugin-dir, --fallback-model or directories added with --add-dir, pass them again when you resume. Directories added mid-session with /add-dir are not restored either. Standard files such as settings.json and settings.local.json are re-read at launch, so anything in them needs no repeat.

Background work does not come back: a background subagent, Bash command or workflow that ended with the old process shows up in the transcript as a note that it did not finish. Claude Code does not start a turn from that note; Claude reads it with your next prompt.

How do I branch a session to try another approach?

Branching copies the conversation so far and switches you into the copy. The original stays intact on disk.

/branch try-streaming-approach

Without a name, the branch is named after the first prompt in the conversation. From the shell, combine a resume flag with --fork-session:

claude --continue --fork-session

The /branch confirmation prints both session IDs, and you return to the original with /resume <original-name>. Two differences matter:

• /branch runs in the same process, so "Allow for this session" permission grants carry over, and in-flight background subagents and background Bash commands keep running, with their output appearing in the branch.
• --fork-session starts a new process without those grants, so you re-approve there.

One warning from the docs: if you resume the same session in two terminals without forking, messages from both interleave into one transcript. If you want two live paths, fork. To undo a bad turn inside one path, the docs point to checkpointing and rewind instead.

Why can resuming be expensive?

Claude Code re-sends the whole conversation on every request. The API reuses (caches) the unchanged start of that conversation and bills the re-read at a lower cached rate, but cached entries expire after a period of inactivity. Each request that hits the cache resets the timer.

The default lifetime depends on how you pay, per the prompt caching docs:

• On a Claude subscription, within your plan's included usage, the main conversation gets a one-hour cache. Once you go over the plan's usage limit and draw on usage credits, it drops to five minutes.
• With an API key, usage credits or a cloud provider, the main conversation gets five minutes.
• You can set the main conversation's TTL yourself with the promptCacheTtl setting or the CLAUDE_CODE_PROMPT_CACHE_TTL environment variable (5m or 1h), on Claude Code v2.1.242 or later. The one-hour option charges a higher rate for cache writes, which costs more on short bursts of work that never sit idle.

If you resume a long session after the cache has expired, the next request reprocesses the full history uncached. On Pro, Max and Ultra plans you may see a "Resume this conversation?" dialog when you resume a long conversation after a long break or on a different model. Its estimate is the share of your 5-hour usage limit that the saved conversation alone would use, and it does not count what you have already used. The cost lands when you send your first message after choosing Resume, not when you select it.

The two choices:

• Resume if the next task needs the saved conversation.
• Start a new conversation if it does not. You can reopen the old one later with /resume.

Compaction does not escape this. After a break longer than the cache lifetime, /compact has to reprocess the history as uncached input to write the summary, which is why it costs the most on an old session. The docs suggest running /compact at a natural break between tasks rather than waiting for auto-compaction mid-task.

To see how your cache is doing, run /usage. After the first response it adds a Prompt cache (main) line to the Session block with the hit ratio, miss count and whether the cache is warm right now (Claude Code v2.1.251 or later).

A practical routine

1. Start named: claude -n <ticket-or-topic>. One session per task.
2. Before a break, nothing special is needed; sessions are saved continuously.
3. Back within the cache window, claude --resume <name> reads most of the history from the cache.
4. Back after a long gap, look at the dialog. If the new task is only loosely related, start a new conversation and paste in a short brief of the state instead.
5. Before trying a risky alternative, /branch first.
6. Use /clear between unrelated tasks; the previous session is saved, and /resume brings it back.

Resuming in scripts and CI

Sessions created with claude -p or the Agent SDK stay out of the picker and out of interactive --continue, but you can resume one by passing its ID to claude --resume. A follow-up question to an existing session looks like this:

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

For a one-off non-interactive run that should write no transcript, add --no-session-persistence to claude -p. Transcripts otherwise live at ~/.claude/projects/<project>/<session-id>.jsonl and are kept for 30 days by default; change that with cleanupPeriodDays in settings.json. The entry format is internal and changes between versions, so use /export or the JSON output rather than parsing the files. To delete a project's transcripts sooner, run claude purge.

How Atlas handles resuming

Atlas runs each engineer as its own Claude Code session. Engineers checkpoint their work, so a restart resumes where they stopped. A thread that has sat idle past Claude's one-hour prompt cache is resumed only when it is small. In one measured case, resuming a cold 378k-token thread just to say "ok" re-wrote 353,191 tokens, while a fresh start with the task costs about 11–25k. You can see the whole team on the Atlas home page.

Naming and branching an engineer's session to try a second approach is not something Atlas does today. That is coming to Atlas, built in, so it will need no setup. Until then, do it yourself in Claude Code with the commands above.

Conclusion

Name your sessions, use --continue and --resume to return to them, and /branch when you want to try something without losing your place. The habit that saves the most plan usage is deciding, each time you come back, whether the next task needs the old conversation. When it does not, start a new one with a short brief.