Session Management

The Claude API keeps no server-side state — every request sends the FULL message history. So "a session" is really a saved conversation transcript you can persist, reopen, and branch.

In Claude Code, session tooling lets you resume a named line of work later and fork a shared starting point into parallel explorations. Mastering this is core to D5 (Context Management) and D3 (Claude Code Workflows) on the architect exam.

Two primitives solve two different problems:

• --resume <name> — continue a single, named session linearly. Same thread, picked up where you left off.
• fork_session — branch from a shared point into multiple independent lines that don't interfere with each other.

Resume = one timeline continued. Fork = one timeline split into parallel timelines.

Use --resume <name> to reopen the exact conversation you left, with its full accumulated context. This is ideal for multi-day work on a single task: a long refactor, an incremental investigation, or a feature you're building across sessions.

The name is your handle — give sessions meaningful names so you can find them later.

fork_session branches from a common starting state — for example, after you've loaded the codebase context and agreed on an approach. Each fork explores a different option without polluting the others' history.

This is the session-level analogue of "try three solutions in parallel": shared setup, independent outcomes.

Reach for --resume when the work is genuinely continuous and the prior context still holds:

• A linear task spanning multiple work sessions.
• Incremental investigation where earlier findings remain valid.
• You want the full reasoning trail intact, not summarized.

Resuming preserves nuance that a summary would flatten — but only if that context is still accurate.

Here's the architect-grade caveat: resumed tool results can be STALE if the codebase changed. If files moved, tests were rewritten, or a dependency was upgraded since you last ran, the old Read and Grep outputs in history now describe a world that no longer exists.

Claude will reason over outdated facts unless you correct them. Resume is not free — it carries whatever was true at capture time.

When context has drifted, a fresh session seeded with a structured summary is often better than resuming. You discard stale tool output and re-ground the model on current reality.

Keep transactional facts — file paths, decisions, open questions — verbatim in a "case facts" block so progressive summarization doesn't make them vague.

Forking shines when you want to compare alternatives fairly. Branch from identical context so the only variable is the approach itself, then evaluate the outcomes side by side.

• Two refactor strategies from the same baseline.
• Different prompt phrasings tested against the same loaded context.
• A risky experiment isolated from your main line.

Because forks don't share ongoing history, one branch's mistakes never contaminate another.

Session strategy mirrors task decomposition. For known sequential steps, a single resumed session acts like a fixed pipeline carrying state forward. For open-ended investigation with multiple viable directions, forking supports adaptive exploration.

Don't force a branch where a line suffices — and don't cram divergent experiments into one ever-growing linear session.

Don't confuse sessions with multi-agent context. Forking branches your own conversation. By contrast, subagents do NOT inherit the coordinator's history — each subagent must be handed its context explicitly in its prompt.

Use sessions to manage your continuity across time; use the hub-and-spoke coordinator pattern to fan work out to fresh agents. They solve different problems.

Putting it together for a multi-day feature:

• Start named, do the shared setup (load context, agree on plan).
• Fork when you need to trial competing approaches.
• --resume the winner across days as you build it out.
• When the repo shifts under you, abandon the stale session and re-seed a fresh one with a verbatim case-facts summary.

Continuity by default, branch when exploring, refresh when reality moves.

Apply the stale-context principle to a real decision.

Key takeaways:

• --resume <name> continues one named session linearly — great for continuous, multi-session work.
• fork_session branches from a shared point into independent parallel lines that don't interfere.
• Resumed tool results can be stale if the code changed — sometimes a fresh session with a structured summary is the better call.
• Keep transactional facts verbatim outside summaries; sessions manage YOUR continuity, while subagents need context passed explicitly.

Continuity by default, branch to explore, refresh when reality moves.