[FEATURE] Conversation Branching - Hierarchical sessions for complex multi-theme work

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When working on complex, multi-theme changes (refactoring, architectural improvements, multi-step features), the current
linear conversation model creates significant friction:

┌─────────────────────────────────────────────────────────────┐
│ Single Conversation                                         │
├─────────────────────────────────────────────────────────────┤
│ 1. Analyze codebase                                         │
│ 2. Create plan with 6 themes                                │
│ 3. Work on Theme 1 (reads 15 files, makes 8 edits)         │
│ 4. Work on Theme 2 (context now polluted with Theme 1)     │
│ 5. Work on Theme 3 (even more pollution)                   │
│ 6. ... context becomes unwieldy ...                        │
└─────────────────────────────────────────────────────────────┘

Pain Point 1: Context Pollution

Large refactorings that touch many files (renaming across 20 files, restructuring modules) accumulate irrelevant
history:

• File reads that aren't relevant to Theme 2
• Debugging back-and-forth specific to Theme 1
• Decisions and trade-offs that only matter for Theme 1

By Theme 3 of a 6-theme plan, the context is bloated with irrelevant history—making Claude less effective.

Pain Point 2: No Isolation When Needed

Sometimes themes should be worked independently to avoid bias. If Theme 1 established a pattern, Theme 2 might benefit
from a fresh perspective, but shared context creates anchoring bias.

Pain Point 3: Manual Orchestration Overhead

The current workaround requires significant manual effort:

# Write plan to file
claude "Write the plan to .claude/PLAN.md"

# Fork a new CLI session manually
git checkout -b theme-1
claude  # New session, manually explain context
"Read .claude/PLAN.md, focus only on Theme 1..."

# Work, commit, then manually sync back
git checkout main && git merge theme-1
claude  # Another new session
"Read git log, update .claude/PLAN.md with progress..."

This duplicates what Claude Code already does well (maintaining TODOs, tracking progress) and requires constant
steering.

Pain Point 4: Lost Learnings

Insights discovered during Theme 1 ("this API is deprecated", "this pattern doesn't scale") don't naturally flow back to
inform the orchestrator's approach to remaining themes.

---

Proposed Solution

Core Concept: Conversation Branching

Model conversations as a tree instead of a line, inspired by Git's branching model:

                        main (orchestrator)
                              │
              ┌───────────────┼───────────────┐
              │               │               │
              ▼               ▼               ▼
          theme-1         theme-2         theme-3
              │               │
              ▼               │
         theme-1.1            │
              │               │
              ▼               ▼
           [done]          [active]
              │
              └──────► merged back to main

Developers can:

• Branch: Spawn a focused child conversation for a specific theme
• Switch: Move between active branches without losing state
• Merge: Complete a branch and flow learnings back to parent
• Nest: Create sub-branches for even more focused work (unlimited depth)

Why Git-Inspired?

Developers already understand branching intuitively:

• Branches isolate work-in-progress
• Commits checkpoint progress
• Merges integrate completed work
• The tree structure is natural for divide-and-conquer

Git already serves as the state synchronization layer—branches and commits persist the actual code changes.
Conversation Branching adds a context synchronization layer on top.

---

Commands

| Command | Description |
|------------------------|----------------------------------------------------------|
| /branch "name" | Create and switch to a new child conversation |
| /branch | List all branches (current marked with *) |
| /switch <name> | Switch to a different branch |
| /done | Complete current branch, return to parent |
| /done --hierarchical | Complete current branch and all children, return to root |

---

Example Session

You: Analyze all TODO[arch] comments and create a prioritized plan.

Claude: I found 6 themes...
[Creates plan with Theme 1-6, writes to .claude/PLAN.md]

You: /branch "theme-1-activity-simplification"

╭─────────────────────────────────────────────────────────────╮
│ 🌿 Created branch: theme-1-activity-simplification          │
│                                                             │
│ Parent: main                                                │
│ Context: Inheriting plan summary (use /branch --isolated    │
│          to start fresh)                                    │
│                                                             │
│ Focus: Theme 1 - Activity Simplification                    │
│ When done: /done to return to main                          │
╰─────────────────────────────────────────────────────────────╯

You: Let's simplify the signTransaction activity...

[... focused work, file edits, commits ...]

You: /done

╭─────────────────────────────────────────────────────────────╮
│ ✓ Completing branch: theme-1-activity-simplification        │
│                                                             │
│ Summary of changes:                                         │
│ • Extended SignTransactionInput with lifetime config        │
│ • Removed buildAndSignTransactionVariants usage             │
│ • 3 files modified, 2 commits                               │
│                                                             │
│ Add learnings to report? (optional)                         │
╰─────────────────────────────────────────────────────────────╯

You: The activity was simpler than expected. Also discovered that
     addressLookupTableAccounts should be cached, added to plan.

╭─────────────────────────────────────────────────────────────╮
│ 🔙 Returned to: main                                        │
│                                                             │
│ Branch theme-1-activity-simplification merged.              │
│ Plan updated with new insight.                              │
│                                                             │
│ Remaining: Theme 2, 3, 4, 5, 6                              │
╰─────────────────────────────────────────────────────────────╯

---

Branch Dashboard

You: /branch

╭─────────────────────────────────────────────────────────────╮
│ Conversation Branches                                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ * main (orchestrator)                    ← you are here     │
│   │                                                         │
│   ├── theme-1-activity-simplification    ✓ merged           │
│   │   └── sub-task-lifetime-config       ✓ merged           │
│   │                                                         │
│   ├── theme-2-type-cleanup               ◐ in progress      │
│   │                                                         │
│   └── theme-3-config-duplication         ○ not started      │
│                                                             │
│ Commands:                                                   │
│   /switch theme-2-type-cleanup    Switch to branch          │
│   /branch "new-name"              Create new branch         │
│   /done                           Complete current branch   │
╰─────────────────────────────────────────────────────────────╯

---

Parallel Work (Multiple Terminals)

Terminal 1 (main):                    Terminal 2:
┌─────────────────────────────────┐   ┌─────────────────────────────────┐
│ main (orchestrator)             │   │ theme-2-type-cleanup            │
│                                 │   │                                 │
│ Monitoring progress...          │◄─►│ Working on Theme 2...           │
│                                 │sync│                                 │
│ /branch                         │   │ /done                           │
│ Shows theme-2 active            │   │ Reports back to main            │
└─────────────────────────────────┘   └─────────────────────────────────┘

---

Configuration Options

Context Inheritance

When creating a branch, control how much parent context flows down:

| Mode | Description | Use Case |
|-----------------------|--------------------------------|-------------------------------|
| --inherit (default) | Digest of parent conversation | Most focused work |
| --inherit full | Full parent conversation | Deep sub-task of same work |
| --isolated | Clean slate, no parent context | Avoid bias, fresh perspective |
| --inherit plan | Only the plan file | Structured handoff |

/branch "theme-2" --isolated
# Starts fresh, reads only code and plan file, no conversation history

Report Format on /done

| Mode | Description | Use Case |
|---------------------|-----------------------------|----------------------------|
| --brief (default) | Git commits + short summary | Quick tasks |
| --detailed | Full summary with decisions | Complex work |
| --custom | Prompts for user input | Capture specific learnings |
| --silent | No report, just switch back | Abandoned/experimental |

/done --detailed
# Generates comprehensive report of what was tried, what worked, decisions made

---

Git Integration

Conversation Branching complements Git, doesn't replace it:

| Aspect | Git | Conversation Branching |
|--------------------|--------------|---------------------------|
| What it tracks | Code changes | Conversation context |
| Isolation | File-level | Context-level |
| Merge | Code merge | Context + learnings merge |
| Persistence | .git/ | .claude/branches/ |

Recommended Workflow

# Git branch and conversation branch often align
git checkout -b theme-1
/branch "theme-1"

# Work naturally...
# Commits happen in Git, conversation stays focused

# When done
/done                           # Complete conversation branch
git checkout main               # Switch git branch
git merge theme-1               # Merge code
                                # Orchestrator sees both:
                                #   - Code changes (git log)
                                #   - Context/learnings (branch report)

Automatic Git Awareness

When returning to parent, the orchestrator can:

• Read git log to see commits made during child session
• Cross-reference with branch report for full picture
• Update plan/TODOs based on actual changes

---

Nested Branching

Branches can nest naturally for divide-and-conquer:

main
└── theme-1-rps-tracking
    ├── sub-delivery-provider-interface     ← Define new interface
    └── sub-migrate-existing-providers      ← Update implementations
        ├── sub-sub-helius-provider
        ├── sub-sub-jito-provider
        └── sub-sub-rpc-provider

Each level maintains its own focused context. /done pops one level at a time, or /done --hierarchical completes all
children and returns to root.

---

Session Persistence

Resumability

Branches persist across terminal sessions:

# Day 1: Start work
claude
/branch "big-refactor"
# ... work ...
# Close terminal

# Day 2: Resume exactly where you left off
claude
# Automatically restores: main → big-refactor

/branch
# Shows full tree with current position

Storage

Branch state stored in .claude/branches/:

.claude/
├── branches/
│   ├── main.json                           # Orchestrator state
│   ├── theme-1-activity-simplification/
│   │   ├── context.json                    # Conversation summary
│   │   ├── report.md                       # Completion report
│   │   └── children/
│   │       └── sub-task-1.json
│   └── theme-2-type-cleanup/
│       └── context.json
└── PLAN.md                                 # Shared plan file

---

Edge Cases

Abandoned Branches

/switch main                    # Leave without completing
/branch --delete theme-2        # Explicitly delete
# or just leave it, like a stale git branch

Conflicts

If parent context changed significantly while child was working:

/done

╭─────────────────────────────────────────────────────────────╮
│ ⚠ Parent context has changed                                │
│                                                             │
│ While you were on theme-2, the following happened on main:  │
│ • theme-1 was completed (3 commits)                         │
│ • Plan was updated                                          │
│                                                             │
│ Options:                                                    │
│ [1] Merge anyway (your work + parent changes)               │
│ [2] Review parent changes first                             │
│ [3] Stay on current branch                                  │
╰─────────────────────────────────────────────────────────────╯

Long-Running Branches

For branches that span days/weeks:

/branch --status theme-2

╭─────────────────────────────────────────────────────────────╮
│ Branch: theme-2-type-cleanup                                │
│ Created: 3 days ago                                         │
│ Last active: 2 hours ago                                    │
│ Commits since branch: 7                                     │
│ Parent (main) commits since: 12                             │
│                                                             │
│ Suggestion: Consider syncing with parent or completing      │
╰─────────────────────────────────────────────────────────────╯

---

Alternative Solutions

Current workaround (manual, tedious):

claude "Write plan to .claude/PLAN.md"
git checkout -b theme-1
claude  # New session, manually re-explain everything
# Work, commit
git checkout main && git merge theme-1
claude  # Another new session, manually sync progress

This requires:

• Constant context re-establishment
• Manual TODO/plan synchronization
• Lost learnings between sessions
• No structured reporting

Other tools: Some IDEs have "workspace" concepts, but none integrate AI conversation context with code branching
naturally.

---

Priority

High - Significant impact on productivity

Complex refactors are common in real-world codebases. The current workaround requires constant manual steering and loses
valuable context/learnings.

---

Feature Category

Interactive mode (TUI)

(Though it spans CLI commands, configuration, and session management)

---

Use Case Example

Scenario: Refactoring a transaction delivery system

1. Claude analyzes TODO[arch] comments, identifies 6 themes:

• Theme 1: Activity simplification (Low effort)
• Theme 2: Type cleanup (Low effort)
• Theme 3: Config duplication (Medium effort)
• Theme 4: Generalize module (Medium effort)
• Theme 5: RPS tracking redesign (High effort)
• Theme 6: Multiple provider instances (High effort)

1. I want to tackle Theme 1 in isolation—it's straightforward but touches 8 files

1. Today: I either pollute the orchestrator context with 8 file reads and edits, OR manually fork a CLI session,

lose the plan context, and manually report back

1. With Conversation Branching:

``
/branch "theme-1"
→ focused work
→ /done "Simpler than expected, also found caching opportunity"
→ orchestrator updates plan with insight
``

1. Result: Clean orchestrator context, captured learnings, natural workflow

---

Additional Context

Why This Matters

For Individual Developers:

• Focus: Work on one thing without mental overhead of "the big picture"
• Clean context: Each theme gets fresh, relevant context
• Natural workflow: Mirrors how we already think about Git branches
• Resumability: Pick up exactly where you left off

For Complex Projects:

• Divide and conquer: Break massive changes into manageable pieces
• Parallel progress: Multiple themes can advance simultaneously
• Knowledge capture: Learnings flow back to inform remaining work
• Audit trail: Clear record of what was tried, what worked

For Claude Code's Evolution:

• Context efficiency: Smaller, focused contexts = better responses
• Plan execution: Natural bridge between Plan Mode and execution
• Collaboration-ready: Foundation for multi-agent or team workflows

---

Summary: Git ↔ Conversation Branching Mapping

| Git | Conversation Branching |
|----------------|------------------------|
| git branch | /branch |
| git switch | /switch |
| git merge | /done |
| Working tree | Conversation context |
| Commit history | Learnings & decisions |

The mental model is familiar. The workflow is natural. The implementation builds on Git as the source of truth for code,
adding conversation context as a complementary layer.

---

Related Issues

This proposal builds on and unifies concepts from:

• #12629 - Session Branching / Conversation Forking (exposes --fork-session via UI)
• #14168 - Git-like context management (/log, /checkout, /branch)
• #10370 - Chat Branching with selective merging (detailed merge strategies)
• #4443 - Named Conversation Branching (/chat save, /chat resume)

What this proposal adds:

1. Orchestrator/child hierarchy - explicit parent-child relationship with learnings flowing back
2. Configurable inheritance - --isolated for fresh perspective, --inherit plan for structured handoff
3. Comprehensive UX mockups - dashboard, command syntax, real-world workflow
4. Session persistence - resume exactly where you left off across terminal restarts