# Claude --resume

> Source: https://aiwiki.ai/wiki/claude_--resume
> Updated: 2026-09-02
> Fact-checked: 2026-09-02
> Categories: Anthropic, Developer Tools
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/) - attribute to "AI Wiki (aiwiki.ai)"
> Cite as: AI Wiki. "Claude --resume." aiwiki.ai, 2 Sept 2026. https://aiwiki.ai/wiki/claude_--resume
> From AI Wiki (https://aiwiki.ai), the free encyclopedia of artificial intelligence. Reuse freely with attribution.

`claude --resume` is a [Claude Code](https://aiwiki.ai/wiki/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](https://aiwiki.ai/wiki/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]

| Command | Result |
|---|---|
| `claude --resume` | Opens the interactive session picker |
| `claude -r` | Opens the same picker using the short form |
| `claude --resume <session-id>` | Resumes the session with that ID |
| `claude --resume <name>` | Resumes an exact session-name or generated-title match; an ambiguous name opens the picker with the text prefilled |
| `claude -r <session> "prompt"` | Resumes the selected session and begins with the supplied prompt |
| `claude -p --resume <session-id> "prompt"` | Sends a non-interactive follow-up to a stored session and exits |
| `claude --resume <session-id> --fork-session` | Copies the prior conversation into a new session ID, leaving the original session separate |

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](https://aiwiki.ai/wiki/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]

| Key | Action |
|---|---|
| `Up` / `Down` | Move through the session list |
| `Right` / `Left` | Expand or collapse a group of matching entries |
| `Enter` | Resume the highlighted session |
| `Space` | Preview the selected conversation; `Ctrl+V` also works in terminals that do not intercept it as paste |
| `Ctrl+R` | Rename the highlighted session |
| `/` or most printable characters | Search the list |
| `Ctrl+W` | Toggle between the current worktree and all worktrees in the repository |
| `Ctrl+A` | Toggle between the current repository and every local project |
| `Ctrl+B` | Toggle a filter for the current Git branch |
| `Esc` | Leave search mode or close the picker |

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]

```bash
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]

```bash
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](https://aiwiki.ai/wiki/prompt_caching) 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]

| Command | Selection rule | Runs where |
|---|---|---|
| `claude --resume` | User chooses from the local picker | Shell, before a session starts |
| `claude --resume <id-or-name>` | Direct local lookup by ID, unique name, or generated title | Shell, before a session starts |
| `claude --continue` | Most recent qualifying conversation associated with the current directory | Shell, before a session starts |
| `/resume` | Switches to another local conversation from inside the current Claude Code process | Interactive CLI session |
| `claude --from-pr <value>` | Opens the picker filtered to conversations linked to a pull request or merge request | Shell, before a session starts |
| `/branch` | Copies the current conversation into another session ID and switches to it | Interactive CLI session |
| `--fork-session` | Makes a new session ID while resuming or continuing | Shell, combined with `--resume` or `--continue` |
| `claude --teleport` | Pulls a Claude Code web session and its branch into a local terminal | Shell, before a local session starts |

`--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](https://aiwiki.ai/wiki/claude_code_cli_flags)
- [Claude Code](https://aiwiki.ai/wiki/claude_code)
- [Claude --continue](https://aiwiki.ai/wiki/claude_--continue)
- [Claude --dangerously-skip-permissions](https://aiwiki.ai/wiki/claude_--dangerously-skip-permissions)
- [Claude Agent SDK](https://aiwiki.ai/wiki/claude_agent_sdk)
- [Prompt Caching](https://aiwiki.ai/wiki/prompt_caching)
- [Context window](https://aiwiki.ai/wiki/context_window)

## References

1. ["CLI reference." Claude Code Docs, Anthropic. Accessed September 2, 2026.](https://code.claude.com/docs/en/cli-reference)
2. ["Manage sessions." Claude Code Docs, Anthropic. Accessed September 2, 2026.](https://code.claude.com/docs/en/sessions)
3. ["Common workflows: Resume previous conversations." Claude Code Docs, Anthropic. Accessed September 2, 2026.](https://code.claude.com/docs/en/common-workflows#resume-previous-conversations)
4. ["Use Claude Code on the web: From web to terminal." Claude Code Docs, Anthropic. Accessed September 2, 2026.](https://code.claude.com/docs/en/claude-code-on-the-web#from-web-to-terminal)
5. ["Claude Code changelog." Claude Code Docs, Anthropic. Accessed September 2, 2026.](https://code.claude.com/docs/en/changelog)
6. ["@anthropic-ai/claude-code package metadata." npm registry. Accessed September 2, 2026.](https://registry.npmjs.org/@anthropic-ai/claude-code)
7. ["Work with sessions." Claude Agent SDK documentation, Anthropic. Accessed September 2, 2026.](https://code.claude.com/docs/en/agent-sdk/sessions)
8. ["Use Claude Code in VS Code: Switch between extension and CLI." Claude Code Docs, Anthropic. Accessed September 2, 2026.](https://code.claude.com/docs/en/vs-code#switch-between-extension-and-cli)