What is Claude fork_session and how and when to use it?

fork_session is a feature in Claude Code (and the Claude Agent SDK) that lets you branch an existing conversation session into an independent copy — like git branch for your AI coding sessions.

What it does

When you fork a session, the SDK creates a new session ID and copies the transcript history up to the point of resumption into a new file. The original session is left completely untouched.

The forked copy has the full context of your problem, your files, and your earlier instructions. If the new direction works, you keep it; if it doesn't, the original session is untouched and you continue from there.

How to use it

1. Inside a running session — /branch command

/branch my-refactor-approach creates a new session with the complete history copied up to that moment, then switches you into it. /fork still works as an alias in many builds.

2. From the CLI — --fork-session flag

claude --resume <session-id> --fork-session lets you fork an existing session from the command line before even opening the terminal UI.

3. Via the Python Agent SDK

Set resume="<session_id>" and fork_session=True in your ClaudeAgentOptions.

options = ClaudeAgentOptions(
    resume="your-session-id",
    fork_session=True
)

In TypeScript, the same API exists in @anthropic-ai/claude-agent-sdk with camelCase names like forkSession.

When to use it

Key use cases include:

• Preserving a known-good state — before attempting a risky refactor, create a branch to safely experiment

• A/B testing prompts — test different instructions from the same conversation state to compare outcomes

Where sub-agents divide one approach into parallel work, forking creates parallel approaches — together they give Claude Code a session-management model that lets you decompose and experiment efficiently.

/branch vs /fork (as of v2.1.161)

As of Claude Code v2.1.161, the semantics split: /branch switches you into a copy of the conversation so you can explore personally. /fork <directive> spawns a background subagent that inherits the full conversation and works on a side task while you continue in the primary session.

TL;DR: Use fork_session when you're at a decision point in a session and want to try two different directions without losing your current context. Think of it as a safety net for experimentation.