Session state, resumption, and forking

What you’ll be able to do

• Use —resume to continue a named investigation session across work sessions
• Use fork_session to create independent exploration branches from a shared analysis baseline
• Choose between resuming (prior context mostly valid) and a fresh session with an injected structured summary (prior tool results stale)
• Tell a resumed session which specific files changed so it re-analyzes them instead of re-exploring everything

What you need to know

A session is accumulated context

Over a long investigation, a session builds up a lot: files read, searches run, tool results, hypotheses ruled out, conclusions reached. That accumulated context is valuable — rebuilding it costs time and tokens — but it's also a snapshot of the world at the moment each tool ran. Managing sessions well means knowing when to carry that context forward, when to branch it, and when to leave it behind.

Named resumption with —resume

Give long-running investigations a name and you can return to them across work sessions. --resume <session-name> continues that specific prior conversation, with its history intact, rather than starting a blank one or picking up whichever session ran last.

Resumption is the right choice when the prior context is mostly still valid: nothing important has changed, and the agent's earlier reads and conclusions still describe the code as it is.

When code has changed: say exactly what changed

The agent's earlier tool results don't update themselves. If you edited retry.py and gateway_client.py overnight, the resumed session still "remembers" the old versions and may reason from them confidently. So when you resume after modifications, tell the agent which files changed and what kind of change it was, and ask it to re-read those files:

This is targeted re-analysis: the agent refreshes what's stale and keeps everything else. The alternative — asking it to re-explore the whole codebase — throws away valid context to fix a problem in two files.

Fresh session with a structured summary

Sometimes most of the prior context is stale: a large refactor landed, files were moved or rewritten, and the old tool results now describe code that no longer exists. Resuming that session means the agent reasons over a history full of outdated reads, and the notes about which parts changed would be longer than what's still true.

In that case, starting a new session with a structured summary injected at the start is more reliable. Carry forward the durable conclusions — the goal, what was established, what was ruled out, open questions — and let the agent gather fresh tool results on the current code.

The decision rule:

• Resume when prior context is mostly valid — and name any specific files that changed.
• Start fresh with an injected summary when prior tool results are largely stale.

fork_session: branches from a shared baseline

Sometimes you want to explore two different approaches from the same starting understanding — compare two testing strategies, or two refactoring approaches, after the agent has already analyzed the codebase. Doing them one after the other in the same session contaminates the comparison: the second approach starts with the first approach's edits, conclusions, and dead ends in its context.

fork_session creates an independent branch from the current session. Each fork starts with the shared analysis baseline and then diverges on its own. What one branch does or discovers after the fork doesn't appear in the other. You pay for the codebase analysis once and get clean, parallel explorations from it.

Key concept

Resume a named session when its context is still mostly valid, and tell it which files changed for targeted re-analysis. Start fresh with a structured summary when prior tool results are stale. Use fork_session to branch independent explorations from a shared baseline.

When a scenario has an agent confidently describing code that has since changed, the issue is stale context: either inform the resumed session about the specific changes, or start fresh with a summary if most of it is out of date.

Practice scenario

Build exercise — Resume, refresh, and fork

Intermediate · 30 min

What you’ll learn

• Running named investigation sessions with —resume
• Choosing between targeted re-analysis and a fresh summary-seeded session
• Comparing approaches with fork_session

1. Start a named investigation session on a small codebase, have the agent analyze a module, then end the session. Make a small edit to one file it read, and resume with --resume <session-name>, naming the changed file and what changed.

   • Why: Resumption keeps valid context; naming the change limits re-analysis to what’s actually stale.
   • You should see: The agent re-reading only the changed file and updating conclusions that depended on it.

2. Now make a sweeping change (move or rewrite most files the agent read). Write a structured summary of the session’s durable conclusions and start a new session with it instead of resuming.

   • Why: When most tool results are stale, a fresh session with a summary is more reliable than a history full of outdated reads.
   • You should see: The agent working from current code without referencing deleted or moved files.

3. From a session that has finished analyzing the codebase, use fork_session to create two branches, each pursuing a different testing or refactoring strategy.

   • Why: Forks share the baseline analysis but diverge independently, so the comparison is clean.
   • You should see: Two branches whose later work doesn’t reference each other.

Exam traps

Resuming a session after code changes without telling the agent what changed

The agent’s earlier tool results reflect the old code. Tell it which files changed so it re-analyzes them.

Resuming a session whose tool results are largely stale instead of starting fresh with a structured summary

When most of the history is outdated, a new session seeded with a summary of durable conclusions is more reliable.

Forcing a full re-exploration when only a few known files changed

Targeted re-analysis of the changed files keeps the valid context and costs far less.

Comparing two approaches one after the other in a single session, so the second inherits the first’s edits and reasoning

Use fork_session to give each approach its own independent branch from the shared baseline.

Starting every work session from scratch and rediscovering context that was still valid

If prior context is mostly valid, resume the named session rather than rebuilding it.

Expecting forked branches to stay in sync or share later discoveries with each other

Forks are independent after the branch point; each sees only the shared baseline and its own work.

Sources

• Claude Developer Platform Docs
• Anthropic, Claude Certified Architect – Foundations Exam Guide v1.0 (July 2026)