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

Preflight Checklist

• [x] I have searched existing issues — this consolidates ideas from #10370 (locked), #12629, #150 (locked), #16276 (locked)
• [x] This is a single feature request

Summary

Claude Code already has /fork and --fork-session. These create independent sessions from a shared history point. What's missing is the return path — bringing conclusions back, navigating the tree, and managing branches as first-class objects. This would make Claude Code dramatically more useful for exploratory work where you need to try multiple approaches before committing to one.

Business Case

Agentic coding sessions are expensive in time, tokens, and cognitive load. When a user reaches message 40 and wants to try two different approaches, they currently must either:

1. Pick one and hope — risk wasting a long session if the approach fails
2. Fork and abandon — /fork works, but conclusions from the winning fork can't flow back; the losing fork's lessons are lost
3. Start over — discard accumulated context entirely

Branching with merge-back solves all three. It turns Claude Code from a linear tool into a tree-structured one, matching how real engineering decisions actually work: explore, evaluate, commit. The closest analogy is git branch + git merge — proven UX that every developer already understands.

What Exists Today

| Capability | Status | Gap |
|-----------|--------|-----|
| Fork from current point | ✅ /fork [name] | Works well |
| Fork on resume | ✅ --fork-session | Works well |
| Rewind current session | ✅ /rewind | Modifies in-place, no branch |
| List/navigate branches | ❌ | /resume shows flat list, no tree |
| Merge conclusions back | ❌ | Must manually copy-paste findings |
| Compare branches | ❌ | No diff between session states |
| Name/tag checkpoints | ❌ | Sessions have IDs, not meaningful names |

Proposed Features (incremental)

Tier 1: Branch awareness (low effort, high value)

/branches or /tree — show the fork tree of the current session lineage.

main (current)
├─ msg 12: fork "try-redis" (15 messages, idle 2h)
│  └─ msg 8: fork "redis-cluster" (3 messages, idle 1h)
├─ msg 28: fork "try-postgres" (22 messages, active)
└─ msg 35: (you are here)

/fork <name> — already exists, but names should be visible in /resume and /branches.

/switch <name|id> — jump to a sibling/child branch. Current session suspends; target session resumes. Equivalent to git checkout <branch>.

Tier 2: Merge-back (medium effort, transformative)

/merge <name|id> — in the current session, inject a summary of another branch's work.

The merge is not replaying tool calls. It's an LLM-generated summary of what the branch accomplished, inserted as a system message. Equivalent to reading a colleague's findings.

/merge try-redis

Inserts into current context:

[Branch "try-redis" merged — 15 messages, 3 file edits]
Summary: Redis approach works for caching but requires sentinel
for HA. Implemented in src/cache.rs. Key finding: latency drops
from 12ms to 0.3ms for repeated queries. Abandoned because
operational complexity too high for single-node deployment.

Merge strategies:

• summary (default): LLM-generated digest of the branch, injected as context
• custom: /merge try-redis "Redis works but too complex, use SQLite instead" — user-written summary
• silent: /merge try-redis --silent — mark as merged for bookkeeping, don't inject anything

Tier 3: Checkpoints and tags (low effort, quality of life)

/checkpoint [name] — bookmark the current conversation state with an optional name. Like a git tag on the message timeline.

/rewind <checkpoint> — rewind to a named checkpoint (currently rewind only goes to auto-created restore points).

This gives users explicit save points before risky operations, without creating a full fork.

Tier 4: Branch comparison (aspirational)

/diff <branch-a> <branch-b> — LLM-generated comparison of two branches' approaches and outcomes.

/diff try-redis try-postgres

Both branches solved the caching problem:
- try-redis: 0.3ms latency, requires sentinel, 3 new dependencies
- try-postgres: 1.2ms latency, uses existing infra, materialized views
Recommendation: try-postgres — simpler operations, acceptable perf.

Implementation Notes

Data model

The JSONL session format already has parentUuid linking messages and isSidechain for subagents. Fork metadata could extend this:

// In session metadata (or a sibling .meta.json)
{
  "sessionId": "abc123",
  "forkOf": "parent456",       // null for root sessions
  "forkAtMessage": "msg789",   // message UUID where fork occurred
  "forkName": "try-redis",     // user-provided name
  "mergedInto": ["parent456"], // sessions this was merged back into
  "checkpoints": [
    {"name": "before-refactor", "messageId": "msg012", "created": "..."}
  ]
}

Context budget

Merge summaries should be treated like compacted context — they compress a branch's work into a few hundred tokens. This is strictly cheaper than the alternative (user manually copy-pasting findings, which wastes context on formatting and repetition).

Git integration (optional, not required)

Branches could optionally map to git branches (as #150 proposed), but this is not required for the core feature. Conversation branching is useful even when not writing code — for research, planning, debugging. Tying it to git would limit the feature unnecessarily.

Prior Art

• #10370: Comprehensive proposal for chat branching with selective merge-back (18 👍, detailed UX mockups, storage format spec). Locked.
• #12629: Request for in-session /fork UI (15 👍). Open.
• #150: Conversation forks as git branches (locked).
• #16276: Fork from specific message (closed as duplicate).
• ChatGPT: Has conversation branching in the web UI (edit a message → creates a branch), but no merge-back.
• Cursor: Has checkpoint/restore but no branching.
• agent-deck (community): Wraps --fork-session in tmux for parallel sessions.

Summary

The primitives exist (/fork, --fork-session, session JSONL with parent links). The missing pieces are branch awareness (see the tree), merge-back (bring conclusions home), and naming (human-meaningful labels). Tiers 1-2 would make Claude Code meaningfully better for any session longer than 20 messages. Tier 1 alone would be a significant improvement with relatively low implementation cost.

---

Addendum: Cross-session context sharing (the git remote analogy)

The branching model above covers forks within a single session lineage. But there's an equally important use case: sending context between unrelated concurrent sessions.

Real workflow

I'm working on two related projects simultaneously:

• Session A: valdivia-analysis/ — computational geometry, GPU kernels, benchmarking
• Session B: vga-paper/ — the academic paper describing Session A's algorithm

Session A discovers that p=10 HLL precision gives R²=0.996 at 3.6x less memory than p=12. Session B needs this finding for the results section. Today I copy-paste between terminals. What I want:

# In Session A (valdivia-analysis)
/push vga-paper "p=10 is the sweet spot: R²=0.996 IHH, R²=0.982 MD, median err 1.25%/0.44%, 4.1s BFS. 3.6x less memory than p=12."

# In Session B (vga-paper) — receives it as injected context
[From session "valdivia-analysis"]: p=10 is the sweet spot: R²=0.996 IHH...

This is git remote for conversations

| Git | Conversation equivalent |
|-----|------------------------|
| git remote add | Register another session as a peer |
| git push | Send a finding/conclusion to a peer session |
| git pull | Request a summary of a peer session's recent work |
| git fetch | Check what's new in a peer without injecting it |

Why this matters beyond single-user workflows

The same primitive enables multi-user agent collaboration:

• My Claude session pushes a question to a colleague's Claude session
• A CI/CD agent pushes test results to a developer's active session
• A research agent pushes findings to a coding agent working on implementation

This connects to #32504 and #24798 but frames it differently: those issues focus on orchestration (coordinator directing workers). The git-remote model is peer-to-peer — any session can push to any other, no coordinator required. It's the difference between a CI pipeline and distributed version control.

Proposed commands

• /push <session-name|id> "message" — send context to another session
• /pull <session-name|id> — request an LLM-generated summary of another session's recent work
• /peers — list sessions that have been registered as peers (or auto-discover by project proximity)
• /inbox — view messages pushed to this session from peers

Messages arrive asynchronously. The receiving session sees them on next user interaction (like checking email), not as interrupts. This keeps sessions autonomous while enabling information flow.