Manage session state, resumption, and forking

A session is the persisted transcript of a conversation: the full message history plus every tool call and tool result the agent accumulated. Claude Code stores sessions locally so you can leave and return to the same line of work later. Each session has a stable identifier, and you continue a specific one with claude --resume <session-name>. Running --resume with no name opens an interactive picker of recent sessions, and --continue (-c) jumps straight back into the most recent session without naming it.

In the Agent SDK the same idea is exposed through query() options. You pass resume: '<session-id>' to reload a prior conversation, or continue (TypeScript) / continue_conversation (Python) to resume the latest one. When you resume, the entire prior context, including old tool results, is replayed into the model. That is powerful when the context is still accurate and expensive to rebuild, but it is exactly why resuming a session whose underlying files have since changed is risky.

# Continue a specific named investigation across work sessions
claude --resume payments-audit
# Or jump back into the most recent session
claude -c

Sometimes you want to explore two divergent approaches, say a Jest migration versus a Vitest migration, without redoing the expensive codebase analysis that both share, and without letting the two explorations contaminate each other. That is what forking is for. Setting forkSession: true (TypeScript) / fork_session=True (Python) when you resume tells the SDK to spin up a new session that branches from the resumed point rather than appending to the original.

The shared analysis becomes a baseline. You fork it once per approach, and each fork gets its own independent session ID and its own future history. The original baseline session stays untouched, so you can always fork it again. This is the clean way to run parallel exploration branches and then compare their outputs side by side.

// Fork the same analyzed baseline into two independent branches
const jest = query({ prompt: 'Plan a Jest migration',
  options: { resume: baselineId, forkSession: true } });
const vitest = query({ prompt: 'Plan a Vitest migration',
  options: { resume: baselineId, forkSession: true } });

Forks are independent, not collaborative: nothing merges them automatically. You read both results and decide, or combine the winning pieces yourself. Contrast this with subagents (task 1.2), where a coordinator actively routes information between agents. A fork is just a parallel timeline of one conversation.

These three operations answer different questions. Resume means "keep going on this exact line of work" and mutates the original session in place. Fork means "start from here, but along a new independent path" and preserves the original. Starting fresh means "discard the accumulated transcript and begin a new session," usually seeded with a hand-written or agent-written summary of what mattered.

The decision hinges on how valid the prior context still is. If the prior context is mostly valid, resume (and, if you need alternatives, fork). If the prior tool results are stale, because files were rewritten, a migration ran, or a lot changed since, resuming drags outdated Read and Grep results back into the model, and the agent will reason about code that no longer exists. In that case a fresh session seeded with a structured summary is more reliable than resuming, because the summary carries forward only the durable conclusions, not the outdated raw tool output.

Think of it as a spectrum of staleness: fully valid context favors resume, a few changed files favors resume-plus-notification, and heavily changed state favors a clean restart with an injected summary.

When you resume after some code changed, but the bulk of the prior analysis is still good, you do not have to choose between blindly trusting stale results and throwing everything away. The middle path is to explicitly tell the resumed agent which files changed and ask for targeted re-analysis of just those, rather than a full re-exploration.

The agent still holds the map of the codebase it built earlier, so a prompt like "Since we last worked, refund_service.py and order_repository.py were refactored to use the new async client. Re-read those two files and update your understanding; the rest of your analysis still holds" is far cheaper and more accurate than making it rediscover the whole module. This keeps the durable structural knowledge and refreshes only the parts that went stale.

Omitting this step is a common failure: the agent silently relies on cached reads and produces edits against code that has moved, so always name the changed files on resume.

Named sessions are what make resumption practical across days. claude --resume <session-name> only helps if you can identify the session you want, so give long-running investigations meaningful names (for example payments-audit or legacy-test-coverage) instead of relying on the anonymous most-recent session. --continue is convenient for a quick return but ambiguous once you have several parallel threads going.

A useful pattern for open-ended investigation is: build one well-named baseline session, resume it by name whenever you return, notify it of any file changes, and fork it whenever you want to try a divergent approach without disturbing the baseline. This gives you a stable trunk plus disposable branches.

Note the vocabulary difference between the CLI and the SDK. The CLI leans on --resume and --continue for interactive use; the SDK exposes resume, continue / continue_conversation, and forkSession / fork_session as programmatic options. They are the same underlying capability surfaced for two different workflows.