Chat Branching: Spawn side-chain conversations with selective merging back to main

Problem

Claude Code conversations can become bloated and lose focus when handling tangential tasks or exploratory work within a single chat. Current limitations:

• Context pollution - Side tasks add irrelevant tokens to the main conversation
• Loss of focus - Main chat becomes cluttered with debugging, research, or experimental work
• No isolation - Can't explore alternatives without affecting main chat history
• Expensive compaction - Compacting loses useful side-task details that might be needed later
• No selective merging - All-or-nothing approach: keep everything or compact everything

Example scenarios where this hurts:

• Main chat: "Design user authentication system"
• Side task: "Debug why bcrypt isn't working" (20 messages of troubleshooting)
• Main chat now has 20 irrelevant debugging messages cluttering context
• Main chat: "Implement API endpoints"
• Side task: "Research which rate-limiting library to use" (exploratory)
• Don't want exploration bloating main chat, just want the conclusion

Proposed Solution

Add "chat branching" - spawn side-chain conversations that inherit context from main but execute independently, then selectively merge results back.

Key capabilities:

1. Spawn side-chain - Create new chat that inherits parent's context
2. Independent execution - Side-chain doesn't affect parent's context/history
3. Selective merge - Choose what to bring back to main chat
4. Context linking - Side-chains reference their parent for full traceability

Proposed commands:

# In main chat, spawn a side-chain
/branch "Debug bcrypt issue"
# Opens new chat with inherited context, focused on specific task

# In side-chain, when done - merge summary back to main
/merge-to-main
# Adds compact summary to parent chat

# Or custom merge with specific instructions
/merge "Tell main chat: bcrypt works with these settings: [details]"

# Or just close without merging
/close-branch
# Keeps side-chain for reference but doesn't affect main

Workflow example:

Main Chat: "Design authentication system"
├─ You discuss high-level architecture
├─ Agent suggests bcrypt for passwords
├─ [/branch "Debug bcrypt configuration"]
│  │
│  └─ Side Chain: "Debug bcrypt configuration"
│     ├─ 20 messages of debugging
│     ├─ Figure out the issue
│     └─ [/merge "bcrypt configured: rounds=12, need to install @types/bcrypt"]
│
├─ Main chat receives: "Completed side task: bcrypt configured successfully. 
│  Key findings: rounds=12, need @types/bcrypt package."
├─ Continue with high-level design (no debugging clutter)
└─ Done

Visual representation in UI:

Main Chat
├─ Message 1: "Design auth system"
├─ Message 2: "Let's use bcrypt..."
├─ 🔀 Branch: "Debug bcrypt" [click to view]
│   └─ Merged back: "bcrypt configured: rounds=12..."
├─ Message 3: "Great! Now let's design the API..."
└─ 🔀 Branch: "Research rate-limiting libraries" [click to view]
    └─ No merge (exploratory only)

Use Cases

1. Debugging without clutter:

Main: Implementing feature X
├─ Branch: "Debug weird TypeScript error" 
│  └─ Merge: "Fixed by updating tsconfig.json"
└─ Continue implementing feature (clean context)

2. Research without bloat:

Main: Design data pipeline
├─ Branch: "Compare Apache Kafka vs RabbitMQ"
│  └─ Merge: "Recommendation: Use Kafka because [3 key reasons]"
└─ Continue with Kafka implementation

3. Parallel task exploration:

Main: Refactor authentication
├─ Branch A: "Explore JWT approach"
├─ Branch B: "Explore session-based approach"
└─ Compare branches, merge winner back to main

4. Preserve detailed work without bloating main:

Main: Build API
├─ Branch: "Configure ESLint rules" (50 messages fine-tuning)
│  └─ Merge: "ESLint configured, see branch for details"
└─ Main chat stays focused, but detailed work preserved

5. Team collaboration (combined with #10368):

Main chat (shared in repo)
├─ Branch by Alice: "Implement auth endpoints"
│  └─ Merged: "Auth endpoints done, tests pass"
├─ Branch by Bob: "Add rate limiting"
│  └─ Merged: "Rate limiting added with redis backend"
└─ Main chat has clean narrative of progress

Implementation Considerations

Context inheritance:

• Side-chain starts with snapshot of main chat's context at branch point
• Changes in side-chain don't affect main
• Main chat can continue independently while side-chain is active

Storage format:

# Main chat: abc123-main.jsonl
{"type": "message", "content": "Design auth system"}
{"type": "branch", "branchId": "xyz789", "title": "Debug bcrypt"}
{"type": "merge", "branchId": "xyz789", "summary": "bcrypt configured..."}

# Side-chain: abc123-branch-xyz789.jsonl
{"type": "message", "parent": "abc123-main", "content": "Let's debug bcrypt..."}
# ... 20 debugging messages ...
{"type": "merge-to-parent", "summary": "bcrypt configured..."}

Merge strategies:

Option 1: Summary only (default)

/merge-to-main
# Agent generates concise summary of side-chain work
# Summary added to main chat as single message

Option 2: Custom message

/merge "Tell main: Use bcrypt with rounds=12, install @types/bcrypt"
# Your custom message added to main

Option 3: No merge

/close-branch
# Side-chain preserved but not merged
# Useful for exploratory work or dead ends

Option 4: Full merge (rare)

/merge-full
# All messages from side-chain added to main
# Use sparingly - defeats the purpose

UI considerations:

• Show branch points as special messages in main chat
• Click branch to view in separate panel/tab
• Badge showing "3 active branches" in chat header
• Visual indicator of which branches have been merged vs abandoned

Deep linking integration (with #10366):

vscode://anthropic.claude-code/chat/local/abc123-main           # Main chat
vscode://anthropic.claude-code/chat/local/abc123-branch-xyz789  # Side-chain

Git compatibility (with #10368):

• Export main chat includes references to branches
• Branches can be exported separately or together
• Team members can see branch structure when importing

Alternatives Considered

1. Manual copy-paste

• Start new chat, copy context manually
• Con: No linking, hard to track, no automatic merge

2. Use /compact aggressively

• Con: Loses details, can't selectively preserve side-task work

3. Multiple separate chats

• Con: No context inheritance, no merge capability, disconnected

4. Single chat with tags/markers

• Con: Still bloats context, harder to navigate, no isolation

Related Features

• Complements #10366 (Deep linking) - can link to specific branches
• Complements #10368 (Chat packages) - branches can be exported/shared
• Could add /list-branches to see all active/closed branches
• Could add /diff-branch <id> to compare branch vs main
• Could support re-branching from historical points in main chat

Benefits

Token efficiency:

• Keep main chat context lean and focused
• Preserve detailed work in branches without penalty
• Only pay for relevant context in each conversation

Organization:

• Clear separation between main narrative and tangential work
• Easier to navigate and understand conversation history
• Better long-term reference (can revisit specific branches)

Flexibility:

• Explore alternatives without commitment
• Parallel work streams
• Safe experimentation (can abandon branches)

Collaboration (with #10368):

• Team members work on branches independently
• Merge results back to shared main chat
• Clean narrative in main chat, details in branches

Current Session (at message 50)
    ├─ Continue here → messages 51, 52, 53... (main work)
    └─ Branch off → new session with context from messages 1-50
                    (try different approach)
                    → Can delete or merge back