Claude --resume

claude --resume is a Claude Code command-line option that reopens a saved Claude Code conversation. Its short form is claude -r. With no value, the option opens an interactive session picker. With a session ID or a resolvable session name, it opens that session directly. A prompt can follow the selector, so claude -r "auth-refactor" "Finish the tests" resumes the named conversation and supplies the next instruction at launch.^[1][2]

Anthropic added --resume and the related Claude --continue option in Claude Code 0.2.93 on April 30, 2025. The two commands both return to stored conversations, but they answer different questions. --continue chooses the most recent qualifying conversation associated with the current directory. --resume lets the user choose a particular conversation, either through the picker or with an identifier.^[2][3][5][6]

Syntax

The option accepts these main forms:^[1][2]

Scroll sideways for more →

The positional value is optional. Claude Code treats it as a session ID when it has the ID form. Otherwise, it resolves the text as a name or title search. The separate --session-id option is not a resume selector. It assigns a valid UUID to the conversation being started, while --resume selects a conversation that already has stored history.^[1][2]

Choosing a session

Interactive picker

Running claude --resume without a value opens the same picker available through /resume inside an active Claude Code session. The launch-time picker initially shows sessions from the current worktree, plus sessions that added the current directory with /add-dir. Background sessions can appear and carry a bg label. Sessions whose first prompt was /loop do not appear. Sessions created through claude -p or the Claude Agent SDK are also omitted from the picker, although either kind can still be resumed directly by ID.^[1][2]

The picker supports keyboard navigation and changes of scope:^[2]

Scroll sideways for more →

Each row uses a user-assigned name when one exists. Otherwise it can show an automatically generated session title, a conversation summary, or the first prompt. The row also shows the time since activity, Git branch, and transcript size. In the all-projects view, it includes the project path. Forks have their own IDs and appear as separate entries, while duplicate records for one session can be grouped under a single expandable row.^[2]

Selecting a session from another worktree of the same repository resumes it in place. If that worktree no longer exists, Claude Code uses the current directory. Selecting a session from an unrelated project normally copies an appropriate cd and resume command to the clipboard. If the original project directory has been deleted, Claude Code instead resumes the conversation in the current directory.^[2]

If the launch-time picker cannot load the selected conversation, Claude Code reports Failed to resume the conversation, prints a retry command, and exits with status 1. A failed switch from the in-session /resume picker behaves differently: it reports the problem but leaves the current conversation running.^[2]

IDs, names, and generated titles

A direct ID lookup searches the current project and its Git worktrees first, then every other project in the Claude Code history on the same machine. Cross-project lookup succeeds only when exactly one other project contains a transcript with messages for that ID. If copied transcript files create multiple possible matches, Claude Code reports the session as not found rather than choosing one arbitrarily. This machine-wide ID lookup applies from Claude Code 2.1.223; earlier versions stopped after the current project and its worktrees.^[1][2]

When no stored conversation matches, the terminal prints No conversation found with session ID: <session-id>. The transcript must still be present on the machine. The broader lookup does not synchronize local histories across computers.^[2][7]

Claude Code also supports human-readable session names. A user can name a new session with claude --name <name> or claude -n <name>, rename one in the picker with Ctrl+R, or run /rename <name> during a conversation. Name resolution covers the current repository and its worktrees. claude --resume <name> resumes a unique exact match. When the name is ambiguous, the command opens the picker and uses the value as its initial search text. By comparison, /resume <name> inside a running session reports an ambiguity error instead of opening a prefilled picker.^[1][2]

Unnamed interactive sessions can have both a default display name and an AI-generated title. These are not interchangeable. The generated title can be passed to --resume, but the default display name cannot. A title created when the user accepts a plan can also serve as a resume handle.^[2]

What is restored

The central purpose of --resume is to put the earlier conversation back into use without asking the user to restate it. Claude Code restores the saved message history, including prior tool calls and tool results. That history can tell the resumed agent which files it read, what it changed, what commands it ran, and what conclusions it reached. It does not, by itself, roll the filesystem back to the state that existed during those turns.^[2][7]

Several other pieces of saved state can return with the transcript:^[2]

• Model: Claude Code normally continues with the model stored in the session. It does not restore that model if the model has been retired, is disallowed by availableModels, is replaced by a launch-time --model or relevant environment variable, or is represented by a provider-specific deployment ID that must be resolved again.
• Agent definition: A session started with --agent or the agent setting keeps that agent's system prompt, tool restrictions, and model when the definition can be found. Claude Code checks the original directory, if it is trusted, and then the directory from which the session is resumed. If it cannot find the agent, it warns the user and falls back to the default system prompt and tools.
• Permission mode: A direct terminal resume by ID or unique name usually restores the previous manual or auto permission mode, subject to safety exceptions and command-line overrides. Picker-based, in-session, and non-interactive resume paths use different rules, described below.
• Active goal: An unfinished goal returns, but its elapsed-time, token-spend, and turn-count baselines start over.
• Scheduled tasks: Unexpired scheduled tasks return. Background Bash processes and Monitor tasks do not.

Some launch-only configuration is deliberately not reconstructed from the transcript. If a session relied on --mcp-config, --settings, --plugin-dir, --fallback-model, or startup directories from --add-dir, those options must be supplied again. Directories added later with /add-dir are not restored either. Normal settings files, including settings.json and settings.local.json, are read again at launch and therefore reflect their current contents, not a frozen copy from the original session.^[2]

This distinction matters when the repository or its configuration has changed. Resuming restores conversation state, but the process still sees the files, settings, credentials, tools, and dependencies available at the time of the new launch. The Claude Agent SDK documentation makes the same boundary explicit: session persistence covers the conversation, not a snapshot of the filesystem.^[7]

Permission behavior

The permission mode after a resume depends on how the conversation is selected. A direct interactive terminal command such as claude --resume <session-id> or a unique claude --resume <name> normally restores the stored mode. The user can override it with --permission-mode or --dangerously-skip-permissions.^[2]

Claude Code does not silently restore every mode:^[2]

• A session that ended in bypassPermissions starts in the mode a new session would use. Bypass must be requested again through an allowed launch flag or an eligible user or managed setting.
• A session that ended in plan mode starts in the mode a new interactive session would use.
• Auto mode is restored only if the account remains eligible for it.
• A manual session remains manual when Claude Code's built-in default would otherwise start a new session in auto mode. An effective defaultMode from settings can take precedence.

Choosing a conversation from the launch-time picker does not restore the conversation's stored permission mode. Claude Code uses the mode that a new session launched with the same command line would receive. When /resume changes conversations inside a running process, the destination conversation inherits the current process's mode rather than its stored one.^[2]

Non-interactive claude -p --resume runs generally use the permission mode that a fresh claude -p call would use. From Claude Code 2.1.246, a session that ended in plan mode can return to plan mode through this path only when all documented conditions hold: the launch supplies --permission-prompt-tool, does not supply an explicit permission mode or bypass flag, does not fork the session, and does not start through channels.^[2]

Forking instead of appending

Ordinary --resume keeps the existing session ID and adds later messages to that conversation. Adding --fork-session changes the operation. Claude Code copies the history into a new session ID, and later turns belong to the new branch. The original conversation remains separately resumable.^[1][2]

claude --resume 550e8400-e29b-41d4-a716-446655440000 --fork-session

The in-session counterpart is /branch [name]. Both mechanisms branch the conversation history, not the working tree. If two branches operate in the same checkout, edits made by one are visible to the other. A Git worktree or another filesystem-level isolation mechanism is needed when file changes must diverge as well.^[2][7]

Forking is also the safe way to explore a second conversational path. Resuming the same session ID in two terminals without a fork causes both processes to write into one transcript, where their messages can interleave. A command-line fork starts a new process and does not inherit one-process permission grants such as "Allow for this session" from the original.^[2]

Non-interactive use

--resume also works with print mode, which makes an existing conversation available to a script. A command can submit a follow-up, request JSON output, and exit after the response:^[1][2]

claude -p --resume 550e8400-e29b-41d4-a716-446655440000 \
  --output-format json \
  "Summarize what changed"

The JSON result contains the response and session metadata. Direct ID selection is important in automation because sessions created by claude -p and the Agent SDK do not appear in the interactive picker. The caller must retain the session ID from an earlier result or another structured interface.^[2][7]

The command-line option and the SDK's resume field share the same underlying idea but are different interfaces. In the SDK, an application captures session_id from a result and passes it through the Python or TypeScript options object. The SDK also has its own continue and fork settings. Those programmatic fields do not change the syntax of the terminal command.^[7]

Setting --no-session-persistence on a print-mode run prevents the conversation from being written to disk, so that run cannot later be selected by --resume. The CLAUDE_CODE_SKIP_PROMPT_HISTORY environment variable suppresses transcript writes in all modes. These controls affect whether resumable data exists, not merely whether it appears in the picker.^[1][2]

Local transcripts and retention

Claude Code normally stores CLI transcripts as JSON Lines files under ~/.claude/projects/<project>/<session-id>.jsonl. The project portion is derived from the working-directory path. CLAUDE_CONFIG_DIR can move the storage root, and CLAUDE_CODE_PROJECT_DIR_NAME can assign a project-directory name when used with a separate config directory.^[2]

Each JSONL line can represent a message, tool use, tool result, or metadata record. Anthropic describes the record format as internal and subject to change between releases. Scripts should use /export, print-mode JSON, hooks, status-line input, or SDK session interfaces rather than depending on a fixed transcript schema.^[2][7]

The default retention period is 30 days and can be changed with the cleanupPeriodDays setting. Once a transcript has been deleted through retention or another cleanup operation, --resume cannot reconstruct it from the model service. CLI transcripts are local. The VS Code extension shares the same conversation history with the standalone CLI, while the Claude desktop app and Claude Code on the web maintain their own histories.^[2][8]

Local sessions and cloud sessions

--resume searches the local history on the current machine. It does not list Claude Code web sessions. The related --teleport option imports a cloud session into a local terminal: Claude Code verifies the repository, fetches and checks out the cloud branch, and loads the cloud conversation. The terminal then has its own local copy, and further local messages do not appear in the original cloud session.^[4]

The distinction is practical as well as terminological. A local session that exists on another computer is not a cloud session and is not found merely because the same user is authenticated. Agent SDK applications that need cross-host resume can mirror transcripts through a SessionStore adapter or arrange to restore the transcript file, but that is application-managed storage rather than behavior provided by claude --resume alone.^[4][7]

Large inactive sessions

On Pro and Max plans, Claude Code can show an additional dialog when a resumed conversation has been inactive for more than about an hour and contains more than 100,000 tokens. At that point the prior prompt cache has expired, so the next request must process the history again. The dialog offers three choices: compact the conversation into a summary before continuing, resume the complete conversation, or resume it and stop showing the dialog in future.^[2]

Compacting reduces what subsequent turns must carry, but the summary can omit details that were present in the full transcript. Resuming the full conversation preserves those details in context, while later requests remain more expensive in proportion to the conversation's size. The first post-expiration request processes the prior history under either choice because the old cache is no longer warm.^[2]

Relationship to other session commands

Claude Code exposes several commands whose names overlap but whose selection rules differ:^[1][2][4]

Scroll sideways for more →

--resume is therefore the explicit-selection form for local history. It is preferable to --continue when several conversations exist, when an automation has retained a specific ID, or when the user wants to branch from a known session rather than whichever one is newest.^[2][3][7]

Development history

• April 30, 2025: Claude Code 0.2.93 introduced claude --resume and claude --continue.^[5][6]
• December 10, 2025: Version 2.0.64 added named sessions, terminal and in-session resume by name, picker grouping for forks, picker preview and rename shortcuts, and a fix for system-prompt flags being ignored on resumed conversations.^[5][6]
• April 1, 2026: Version 2.1.90 stopped showing print-mode and SDK sessions in the picker, sped up the all-projects view, and fixed a first-request prompt-caching regression affecting resumed sessions with deferred tools, MCP servers, or custom agents.^[5][6]
• April 7, 2026: Version 2.1.94 made sessions in another worktree of the same repository resume directly rather than returning a cd command.^[5][6]
• August 2026: npm records version 2.1.223 at 22:51 UTC on August 5, while Anthropic's rendered changelog dates it August 6. The session documentation identifies it as the boundary after which direct ID lookup searches other local projects as well as the current project and its worktrees.^[1][2][5][6]
• September 1, 2026: Version 2.1.257 fixed a background conversation appearing twice in --resume, and changed claude --resume <session-id> --bg to continue under the original ID when no process was already running that session. If it must create a copy, Claude Code now says so.^[5][6]

These changes also show why older help pages and installations can behave differently. The current documentation is the authority for the current CLI, while the changelog records which behaviors arrived or changed in particular versions.^[1][5]

See also

• Claude Code CLI Flags
• Claude Code
• Claude --continue
• Claude --dangerously-skip-permissions
• Claude Agent SDK
• Prompt Caching
• Context window

References

1. ^"CLI reference." Claude Code Docs, Anthropic. Accessed September 2, 2026.
2. ^"Manage sessions." Claude Code Docs, Anthropic. Accessed September 2, 2026.
3. ^"Common workflows: Resume previous conversations." Claude Code Docs, Anthropic. Accessed September 2, 2026.
4. ^"Use Claude Code on the web: From web to terminal." Claude Code Docs, Anthropic. Accessed September 2, 2026.
5. ^"Claude Code changelog." Claude Code Docs, Anthropic. Accessed September 2, 2026.
6. ^"@anthropic-ai/claude-code package metadata." npm registry. Accessed September 2, 2026.
7. ^"Work with sessions." Claude Agent SDK documentation, Anthropic. Accessed September 2, 2026.
8. ^"Use Claude Code in VS Code: Switch between extension and CLI." Claude Code Docs, Anthropic. Accessed September 2, 2026.