[FEATURE] Conversation Branching — full spec for fork, merge, and tree navigation

This issue consolidates ideas from several related proposals that were auto-closed and locked:

• #10370 (@AlexZan) — chat branching with selective merge-back
• #12629 (@jonkhler) — in-session fork UI
• #150 (@adamavenir) — conversation forks as git branches
• #16276 (@jdxbla) — fork from specific message
• #24798 (@hmcg001) / #32504 (@SecludedCorner) — inter-session communication

Also builds on work by @asheshgoplani (agent-deck fork implementation) and @smconner (search-term consolidation on #10370).

If this captures what you were after, a 👍 on the issue would help signal demand. Feedback welcome — especially on the merge-back semantics (Tier 2) and cross-session push/pull (the git-remote addendum).

cc @NickNick @tbrebant @wxtry @kyryl-lebedin @marcindulak

Great consolidation, @stiege — especially the Addendum section with the git remote analogy.

We're running a multi-team coordinator workflow that maps directly to your cross-session push/pull proposal:

• Research team session: 24 AI agents (#0–#23) doing architectural research and voting on design decisions
• Dev team session: 7 agents running SOPs (Standard/Release/Hotfix/DOC/Simulation)
• Coordinator session (me): bridges the two teams — generates master letters, transfers deliverables, maintains shared memory

Today the coordinator manually transfers files between teams via shared directories and updates memory files. The pain points:

1. No session discovery — I can't see if the research or dev session is still running
2. No push capability — when dev finishes a build, research doesn't know until I manually relay it
3. File-based mailbox is fragile — no delivery confirmation, no read receipts, sessions don't notice new files without polling

Your proposed /push + /inbox would eliminate our entire manual relay workflow. Specifically:

# Coordinator pushes research output to dev session
/push dev-team "Cycle 02-8 research complete. 7 decisions passed. Plan32 spec ready in share/research_team_suggestion/cycle02-8/"

# Dev session checks inbox on next interaction
/inbox
→ [From coordinator]: Cycle 02-8 research complete...

The peer-to-peer model (vs. coordinator-directed) is key — sometimes the dev team needs to push findings directly to research without going through the coordinator.

+1 on the full proposal. Tiers 1-2 are valuable, but the Addendum is what would be transformative for multi-agent workflows.

Use case: retroactive fork with selective compaction

Related: #28716 (summarize before here)

There's a variant that sits between Tier 1 and Tier 2: retroactive branch-and-compact. The scenario:

You're 60 messages in and realize messages 35–60 went down a tangent. You want to:

1. Fork at message 35
2. The new session gets messages 35–60 verbatim (full fidelity)
3. Messages 1–34 get compacted into a summary as the session's preamble

The result is a clean, focused session for the tangent — with enough compressed context to remain coherent, but without dragging along the full weight of the earlier conversation.

This differs from /fork today (which copies everything up to the fork point verbatim) and from /compact (which compresses the whole session indiscriminately). It's the combination: fork + selective compaction at the branch point.

The git analogy would be git checkout -b tangent && git rebase --squash main~34 — take the recent commits as-is, squash the old history.

A hook-based approach can implement basic conversation branching via checkpoints:

PROMPT=$(cat | jq -r '.userPrompt // empty' 2>/dev/null)
BRANCH_DIR="$HOME/.claude/branches"
mkdir -p "$BRANCH_DIR"
if echo "$PROMPT" | grep -qiE '(/branch|save checkpoint|fork here)'; then
    NAME=$(echo "$PROMPT" | sed 's/.*\(branch\|checkpoint\|fork\)\s*//' | head -c 30 | tr ' ' '-')
    [ -z "$NAME" ] && NAME="checkpoint-$(date +%s)"
    CHECKPOINT="$BRANCH_DIR/$NAME"
    mkdir -p "$CHECKPOINT"
    git stash create > "$CHECKPOINT/git-stash" 2>/dev/null
    git diff --stat > "$CHECKPOINT/changes.txt" 2>/dev/null
    git log --oneline -5 > "$CHECKPOINT/history.txt" 2>/dev/null
    echo "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$CHECKPOINT/timestamp"
    jq -n --arg n "$NAME" '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"Checkpoint saved: " + $n + ". Use /branch restore <name> to return to this state."}}'
fi
if echo "$PROMPT" | grep -qiE '/branch restore'; then
    NAME=$(echo "$PROMPT" | sed 's/.*restore\s*//' | tr ' ' '-')
    CHECKPOINT="$BRANCH_DIR/$NAME"
    if [ -d "$CHECKPOINT" ]; then
        STASH=$(cat "$CHECKPOINT/git-stash" 2>/dev/null)
        [ -n "$STASH" ] && git stash apply "$STASH" 2>/dev/null
        jq -n --arg n "$NAME" '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"Restored checkpoint: " + $n}}'
    fi
fi
if echo "$PROMPT" | grep -qiE '/branch list'; then
    LIST=$(ls "$BRANCH_DIR" 2>/dev/null | while read d; do echo "  $d ($(cat "$BRANCH_DIR/$d/timestamp" 2>/dev/null))"; done)
    jq -n --arg l "$LIST" '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"Saved checkpoints:\n" + $l}}'
fi
exit 0

This gives you basic /branch, /branch restore, and /branch list commands via hooks.

Disclaimer: The comment below is generated by claude code. The idea is mine, the words and the research is not. But the entire content is under my responsibility.

Prefix cache reuse makes fork/merge nearly free - here's why

Building on the discussion here and in related issues (#10370, #18840, #28415, #12790), I want to add an

The three-way dilemma today

As emernic noted in #12790, the current options are all unsatisfying:

| Mode | Sees parent context? | Prefix cache hit? | Intermediates pollute parent? |
|---|---|---|---|
| Inline (default) | Yes | Yes | Yes (permanent) |
| Agent / context: fork | No | No (fresh prompt) | No |
| Workarounds (log replay, etc.) | Partial | No | Varies |

Why branching is cheaper than you'd expect

The Anthropic API caches KV states for matching prompt prefixes. A branched execution that copies the parent's message array as its prefix would hit the cache automatically - cached tokens are ~90% cheaper and near-instant. The branch diverges only at the append point (the scoped task + tool calls), so the entire shared prefix is served from cache.

This means fork/merge isn't just a convenience - it's cheaper than the current subagent approach, which rebuilds its entire prompt from scratch every turn with zero cache benefit.

For a session at 100k tokens with a skill producing 20k tokens of intermediate output:

• Inline: 100k (cached) + 20k permanently added. Stale intermediates compete with useful context at compaction time.
• Subagent: Fresh prompt every turn, no cache reuse. Clean parent, but expensive and context-blind.
• Branched: 100k (cached) + 20k in branch only. Parent gets back a small result. Next turn: ~100.5k with full cache hit.

For N parallel branches from the same point (the scenario in #28415), all N share the same cached prefix - the redundant ~50k x (N-1) token cost disappears entirely.

Implementation: harness-level only, no API changes

The harness already manages the message array:

1. Fork: Copy the current message array. Append the scoped task prompt.
2. Execute: Send to the API normally. Shared prefix hits cache. Tool calls append to the copy only.
3. Merge: Insert the final assistant message (or structured return value) into the original array. Discard the copy.

This could surface as:

• context: branch in skill frontmatter (a third option alongside inline and fork, as Crazytieguy suggested the parent should control)
• branch_from_current: true on the Agent tool
• A merge-back path for the existing /fork command (completing the gap identified in this issue)

Relation to the tier structure

This supports the tiered approach proposed here. Prefix cache reuse makes Tier 1/2 forks cheap enough to be casual - you wouldn't need to think twice about branching for a quick investigation, because the cost is essentially "only pay for the new work, not for re-reading the conversation."

Great spec. One thing I'd add to Tier 1 that would cover a very common workflow:

/branch "name" --from N — Create a named branch from N prompts ago, without leaving the current session.

Use case: You're deep in a technical architecture discussion and it naturally forks into business/legal implications. You realize 3 prompts later that you want both threads. Today this
requires: /branch (only from current point) → exit → picker → rename → re-enter → /rewind. By then you've lost your flow.

The proposed command would:

1. Create the branch from the specified history point
2. Name it immediately (no need to exit and use the picker)
3. Stay in the current session (you switch to the new branch when you're ready via /switch)

Related: there's currently no way to see the current session ID from inside a session (/session-info or similar), which makes managing parallel branches very hard.

[dictated to me by my claude code after we discussed it, Pietro]

Hi Alex,

Your #32631 spec stuck with me — modeling conversation branching as git branch + fork → evaluate → merge-back, with a tree to navigate the rest. Cleaner than how Claude Code thinks about it today.

I noticed swarm-mcp too — you're already running parallel Claude agents in Docker. So you've probably hit the thing I'm chasing: when several branches finish overnight, deciding which one is actually safe to merge back is its own job, separate from getting the work done.

One genuine question, no pitch: when you've got multiple parallel agent outputs to merge, do you enjoy going through each one yourself — reading the diff, working out why it changed what it did — or would you rather just have a fast, trustworthy read on which branch is merge-safe and skip the deep-dive?

I'm async-only and a few timezones off, so no call — a one-line reply is plenty.

For context on why I'm asking: I'm building the thing that sits after the agent finishes. The agent does the work overnight; in the morning you get a short report that tells you in a few minutes whether it's safe to merge, instead of reading all of it line by line.

Best,
Shiyu

the thing I keep hitting with fork/merge proposals like this: the blocker isn't the merge command, it's that the parent session keeps auto-compacting underneath you. you fork at message 40, explore a branch or two deep, and by the time you want to merge findings back the parent's context already got summarized out from under you, so there's nothing faithful left to merge into. tree-structured work only holds if every node keeps its full context independently and survives a restart. the parentUuid plumbing handles lineage fine, but lineage isn't the same as preserved context per node. separate those two and merge-back gets a lot more tractable.

For Tier 1/3 (branch from a past message + checkpoint navigation), there's something working today: hit Ctrl-B in ccfind (claude-grep) on any session row to fork that session at any past user message — creates a new session file in Claude Code's native /btw-compatible format. No merge-back yet (Tier 2), but the branch-from-checkpoint UX is functional.

brew install coolcorexix/tap/claude-grep

— happy for this to be superseded by a native impl, just sharing as existence proof.

I just created this simple tool: branch-graph, as a workaround for the following gap mentioned in this issue until it's implemented natively.

| Capability | Status | Gap |
|------------|--------|-----|
| List/navigate branches | ❌ | /resume shows a flat list instead of a branch tree |

The branch-graph UI looks like the following, making it much easier to navigate between branches.

Branches in my-project

1  ● a4f3d8c2  Draft initial README outline
2  ● 9b6e1f47  Design payment retry logic
3  ├─● c8a2b91d  stripe-webhooks
4  │  ├─● 5e7f3a06  Add signature verification for Stripe webhooks
5  │  └─● 1d4c9b82  Handle partial refunds and capture expiration (most recent)
6  └─● 7f2e8c15  paypal-webhooks
...