Resume the session your investigation needs

Learning objective

Resume named investigations with claude --resume <name> or a captured SDK session ID, retaining useful previous context.

Core idea

For an architect returning to an investigation, the useful unit of continuity is a specific conversation. Resume that conversation when its analysis, constraints, and evidence still apply. Starting an unrelated conversation discards useful work; continuing whichever session ran last can restore the wrong work.

Claude Code saves conversations locally. The Agent SDK also writes session history to disk automatically. That history contains prompts, tool calls, tool results, and responses. Resumption gives the agent the earlier analysis so your follow-up can build on decisions already made. It does not make an earlier file read a fresh observation of the filesystem.

Choose a human-readable name for an interactive investigation and capture a session ID for a programmatic one. These handles solve selection. Evidence freshness is a separate decision, covered in 1.7.3; branching into alternatives is covered in 1.7.2.

How it works

Name the workstream before returning to it

At startup, claude --name auth-timeout-investigation (short form -n) gives the session a display name. During an interactive session, /rename auth-timeout-investigation sets or changes its name. Return from the shell with this command:

claude --resume auth-timeout-investigation

Here, auth-timeout-investigation is an example name you assigned, not an automatically selected session. The CLI also accepts a session ID with --resume (short form -r). With no argument, claude --resume opens the session picker. Inside an active session, /resume opens the picker, and /resume auth-timeout-investigation switches to the named conversation.

Name resolution covers the current repository and its worktrees. An exact, unambiguous name resumes directly. If the shell command finds an ambiguous name, it opens the picker with that name as a search term. Inside a session, an ambiguous /resume <name> reports an error; use /resume without an argument to choose. Descriptive names help selection, but the name alone is not proof that you restored the intended investigation.

A session you never name still gets two labels. Claude Code generates a title from your first prompt, and that title works as a resume handle. An interactive session also gets a default display name such as my-app-3f, which identifies it in listings of running sessions but is not a resume handle: --resume does not find a session by it. A claude -p run started from a shell or script gets no generated title.

The CLI’s ID lookup searches the current project and its worktrees, then other projects on the machine. Cross-project ID lookup requires an unambiguous transcript. That lookup behavior requires Claude Code v2.1.223 or later; before that version, ID lookup covered the current project and its worktrees. An ID selects stored history; it does not fetch a missing transcript from another host.

Capture the SDK’s session ID

For an Agent SDK workflow, save the session_id from the result message. In Python, the message is ResultMessage, and its field is message.session_id. In TypeScript, SDKResultMessage has the same session_id field. Do not convert that field to sessionId merely because the surrounding TypeScript options use camel case.

The result carries the ID on success and error outcomes. A single-shot query() raises after yielding an error result, so capture the ID while iterating and catch the subsequent exception. A connection or process failure can yield no result message; in that case, the result-based capture has no ID to save. TypeScript also exposes the ID on the init system message; Python nests the init data inside SystemMessage.data.

Pass the captured ID to resume on the next query() call. Python uses ClaudeAgentOptions(resume=SESSION_ID); TypeScript uses options: { resume: sessionId }. SESSION_ID and sessionId stand for your captured value. The follow-up prompt describes the next question rather than repeating the entire investigation. Set the session’s working directory through cwd when the workflow needs a particular checkout.

This is Agent SDK session management. It is distinct from the application-owned Messages API history described in 0.2. A stored SDK session ID is not a substitute for the Messages API’s messages array.

Separate selecting a session from continuing the last one

In Claude Code, claude --continue (-c) loads the most recent conversation in the current directory. It skips sessions created with claude -p or the Agent SDK unless you also pass -p. The SDK’s Python continue_conversation=True and TypeScript continue: true resume the most recent session in the directory. Use that shortcut when the application runs one conversation at a time and the most recent session is reliably the one you want. With multiple investigations, use an explicit resume ID.

Python’s ClaudeSDKClient automatically continues the same session across calls to client.query() on that client. That is useful within one process. Capturing an ID and resuming explicitly supports returning after a process restart or choosing another stored conversation. The distinction is selection, not whether the agent can perform several turns within one call: a single query() already runs the agent loop.

Check what continuity actually restores

A resumed transcript includes earlier tool calls and results. If a tool was interrupted before its result was recorded, resumption does not finish or automatically rerun that tool. Claude Code marks it as cut off and instructs the agent to check whether it took effect before running it again, unless CLAUDE_CODE_RESUME_INTERRUPTED_TURN is set. Treat interrupted execution as an outcome to investigate, not completed evidence.

Do not assume the transcript recreates every launch setting. Claude Code documents that session-specific flags such as --mcp-config, --settings, and --add-dir need to be passed again when the resumed work depends on them. Standard settings files are re-read at launch. Restored history and the environment available to act on it are separate inputs.

Key distinctions and trade-offs

Name versus ID: A name makes interactive work findable. A captured ID selects a specific SDK conversation without depending on which session ran last.

Resume versus continue: Both add to existing history. resume selects it explicitly; the continue options select the most recent session in the directory:

Remembered evidence versus live evidence: A saved tool result preserves what a tool returned then. It does not establish what the tool would return after files change.

Resumption saves re-exploration when the earlier context is useful. Its cost is carrying assumptions and observations that you must assess before acting. If the transcript is unavailable on a replacement host, an ID alone cannot restore it; retain the transcript or pass needed findings into a fresh prompt.

Architecture / decision scenario

A developer investigates intermittent authentication timeouts in Claude Code and names the conversation auth-timeout-investigation. The session reads the refresh path, rejects a configuration hypothesis, and records an unresolved question about concurrent refresh requests. The developer then works on an unrelated build problem in another session.

The next morning, the developer uses claude --resume auth-timeout-investigation, checks that the restored discussion concerns refresh concurrency, and asks for a test of the unresolved hypothesis. Continuing the most recent conversation would select the build investigation instead. The named session preserves the rejected hypothesis and the reasoning behind the next test.

An automated developer-productivity service supports the same workflow with the Agent SDK. It stores each investigation’s ResultMessage.session_id against its work item, then supplies that value through resume when the work item returns. It does not choose continue_conversation=True across several investigations. If code changed overnight, the next prompt names the changed files and requests re-analysis as described in 1.7.3.

Common exam traps

Avoid these selection and continuity mistakes:

• Treating --resume without an argument as a direct return to one named investigation.
• Using claude --continue to return to one of several investigations in the same directory.
• Passing a session’s default display name, rather than a name you set or its generated title, to --resume.
• Using the SDK’s continue option when multiple stored conversations compete to be most recent.
• Passing a CLI display name where the SDK’s resume option requires a session ID.
• Capturing sessionId from a TypeScript result instead of its documented session_id field.
• Treating a resumed tool result as a fresh read, or an interrupted tool call as completed work.

What to remember

Name interactive investigations, capture SDK result IDs, and resume the conversation you intend. Preserve useful reasoning without assuming that stored tool results or the previous launch environment remain valid. Selection restores continuity; targeted re-analysis establishes freshness.

Knowledge check

References

• Anthropic, Manage sessions
• Anthropic, CLI reference
• Anthropic, Work with sessions