branch-ai

The reasoning canvas for any AI CLI. Works with Claude Code, OpenAI Codex, Google Gemini, or Factory.ai Droid — captures each tool's reasoning as a navigable, forkable tree. Walk backward through the thinking, explore alternative paths from any point, or add a new fact mid-thought and watch how the conclusion changes.

See it live: Try the public demo — view real reasoning trees. To create your own and fork them, install locally below.

Why this exists. When an AI works through a hard problem, the reasoning vanishes the moment you see the answer. Branch preserves every reasoning step, lets you rewind to any point, and explore "what if I changed this assumption?" — without starting over.

What is Branch AI?

Branch is a reasoning canvas for AI CLIs that captures the extended thinking from Claude Code, OpenAI Codex, Gemini CLI, and Factory Droid as a navigable, forkable tree. Instead of watching reasoning scroll past in your terminal and vanish, Branch turns it into a tree you can rewind, fork from any step, and edit mid-thought.

Why Branch

Terminal output is a transcript — you read it once and it's gone. Branch keeps the reasoning as structure. From any node you can fork an alternative path, inject a new fact and re-reason from that point, or record why you decided what you decided and what would change the answer later. It works with four AI CLIs, runs fully local by default, and ships an MCP server so agents can externalize their own reasoning.

Branch vs. the alternatives

| | Branch | Scrolling terminal output | LLM tracing (LangSmith, Langfuse) | Chat/session loggers | |---|---|---|---|---| | Captures reasoning as a navigable tree | Yes | No (linear text) | Spans/timeline, not forkable | Messages only, not reasoning steps | | Fork from any step / explore alternatives | Yes | No | No | No | | Inject a fact mid-thought and re-reason | Yes | No | No | No | | Built for interactive CLI use (no app instrumentation) | Yes | n/a | No — for apps you build | Varies | | Local-first, no API key required | Yes | Yes | No (hosted) | Varies |

Honest scope: if you need production tracing across a deployed agent app with dashboards and eval runs, use LangSmith/Langfuse — that's what they're for. Branch is for the interactive loop: one developer, one hard question, at the CLI, wanting to see and steer the reasoning.

When to use Branch

• You're working a hard decision through Claude Code / Codex / Gemini and want to see how it got there, not just the answer.
• You want to explore "what if I changed this assumption?" without re-running the whole prompt from scratch.
• You want to record a decision — what you picked, what you rejected, and what would make you revisit it.
• You want your Claude Code agent to externalize and fork its own reasoning via MCP.
• You want to compare or merge the reasoning from two different runs or two different models.

FAQ

Does Branch need an API key? No. Branch uses your existing CLI auth (Claude Code, Codex, Gemini, or Droid). It never asks for its own API key.

Which AI CLIs does it support? Claude Code (richest reasoning capture), OpenAI Codex CLI, Google Gemini CLI, and Factory Droid. Run branch doctor to see which are on your PATH.

Is my reasoning uploaded anywhere? No, unless you opt in. Sessions save to ~/.branch/sessions/ on your machine. Sharing is per-session and explicit (branch share <id>).

What's the MCP server for? branch-mcp gives Claude Code 13 tools so an agent can externalize its reasoning as a tree, fork it, inject facts, diff/merge runs, and record decisions — from inside a session.

Does it capture everything the model "thinks"? No. It captures the surfaced reasoning steps when extended thinking is on. Token-level cognition is never exposed by any API — Branch captures what the model narrates, not everything it computes.

Supported CLIs

• Claude Code — full thinking-block capture (richest reasoning)
• OpenAI Codex CLI — captures reasoning summaries from o3 / gpt-5
• Google Gemini CLI — captures Flash thinking-mode output
• Factory.ai Droid — routes across underlying models; captures thinking when the routed model supports it

Run branch doctor after install to see which are available on your PATH.

What you get

• branch "prompt" — CLI that captures reasoning as a navigable tree (auto-detects which AI CLI to use, or pass --cli claude|codex|gemini)
• branch-mcp — MCP server so Claude Code agents can externalize their own reasoning, fork it, or add facts mid-thought
• Web viewer — React Flow canvas where you click any node to explore an alternative path or add a new fact
• branch decide — record what you decided, what you rejected, and what would change the answer later
• branch doctor — see which AI CLIs are installed and which one Branch will use by default

Requirements

• Node 20.5+ for the standalone CLI (Node 20.6+ for source development with node --import tsx)
• Node 20.9+ for the optional local viewer
• At least one AI CLI on PATH:
  • Claude Code signed in (Claude Pro, Max, or Team subscription)
  • OpenAI Codex CLI (codex binary)
  • Google Gemini CLI (gemini binary)
  • Factory.ai Droid (droid binary)
• Branch uses your existing CLI auth — no API keys required by Branch itself

Install

npm install -g branch-ai

The published CLI package excludes the viewer. Clone the repository to run the local viewer with Node 20.9+. Viewer auto-start failures are handled by the CLI; they do not raise the standalone CLI Node requirement.

Quickstart

# Terminal 1 — start the viewer
git clone https://github.com/nikolas-sapa/branch-ai && cd branch-ai
npm run viewer
# viewer runs on http://localhost:7432

# Terminal 2 — run the CLI
branch "Should I deploy on Friday afternoon? Think carefully through the tradeoffs"
# opens the reasoning tree in your browser automatically

CLI

branch [--cli claude|codex|gemini|droid] [--model <model>] [--local] "your prompt"

• --cli — pick an AI CLI. Defaults to auto-detect (first available on PATH).
• --model — model name (each adapter has its own defaults; e.g. sonnet for Claude, gpt-5 for Codex, gemini-2.5-flash for Gemini, default for Droid)
• --local — skip auto-sharing for a single run when BRANCH_AUTO_SHARE=1 is set (auto-share is OFF by default — see Privacy section)

Run branch doctor to see which CLIs are available and which Branch will use by default.

Sessions are saved to ~/.branch/sessions/<id>.json. The viewer reads them from there.

All commands

| Command | What it does | |---|---| | branch --help / branch -h | Show usage without running a prompt | | branch --version / branch -V | Show installed package version | | branch "prompt" | Run a prompt and open the reasoning tree | | branch list | Recent sessions | | branch search <query> | Search across all sessions including decision conclusions | | branch share <id> | Upload a session to Vercel Blob for sharing | | branch decide <id> | Record a decision anchor for a session | | branch decisions | List all sessions with recorded decisions | | branch export <id> | Export as Markdown or Mermaid | | branch diff <a> <b> | Compare two sessions | | branch tag <id> <tag> | Tag a session | | branch pin <id> | Pin a session to the top of the list | | branch replay <id> [--model X] | Re-run a session's original prompt (optionally with a different model) and link the new run back to the source | | branch merge <a> <b> | Synthesize two sessions into a third — finds agreement, divergence, and a unified answer | | branch watch on\|off\|status | Install/remove a Claude Code Stop hook that auto-saves every CC session as a Branch tree | | branch mcp install <client> | Add the branch-mcp server to a client's config file (claude-code, claude-desktop, cursor, codex, cline) | | branch mcp install --all | Install branch-mcp into every supported client at once | | branch mcp uninstall <client> | Remove branch-mcp from a client's config | | branch mcp status | Show which clients have branch-mcp installed |

Environment variables

• BRANCH_VIEWER_URL — override where the CLI prints the viewer link. Default: http://localhost:7432.
• BLOB_READ_WRITE_TOKEN — Vercel Blob token. Required for branch share <id> (manual upload). By itself, this does NOT cause auto-upload — see BRANCH_AUTO_SHARE.
• BRANCH_AUTO_SHARE — set to 1 to opt in to auto-upload of every branch "prompt" run. Off by default. Use --local to opt out per-run when auto-share is on.

Decision anchors

After a reasoning session, record what you actually decided:

branch decide <sessionId>
# interactive prompts: conclusion, rejected alternatives, confidence, revisit trigger

# or non-interactive:
branch decide <id> --conclusion "Build modular monolith" --rejected "Microservices;Mongo migration" --confidence high --revisit-if "Team grows past 15 engineers"

Decisions show up in branch list with a [decided] marker and the conclusion line. branch decisions shows only settled questions. The viewer renders a decision card at the top of the session.

Gallery

The viewer ships a /gallery route with a hardcoded list of curated reasoning examples you can explore in the tree canvas:

http://localhost:7432/gallery

Click any card to open the full session — fork from any node, add a new fact, or compare with branch diff.

Privacy note: The gallery is NOT auto-populated. Only the sessions explicitly listed in viewer/lib/gallery.ts and bundled into viewer/public/gallery-sessions/ ship with the viewer. Your own sessions in ~/.branch/sessions/ are private to your machine unless you choose to share them.

Privacy

By default, Branch is fully local:

• Sessions save to ~/.branch/sessions/<id>.json — only on your machine
• The viewer reads from your local disk
• Nothing leaves your machine unless you explicitly share

Sharing is opt-in per use:

• branch share <id> — manual upload of one session to public Vercel Blob
• BRANCH_AUTO_SHARE=1 (env var) — opt in to auto-upload every run; remove the var to stop
• --local flag — skip auto-share for a single run when BRANCH_AUTO_SHARE=1 is set

When you share, the entire session JSON (prompt + reasoning tree + final answer + decision) is uploaded to a publicly readable URL. Don't share sessions containing secrets, internal company data, or anything you wouldn't post on GitHub.

MCP server — use Branch from inside Claude Code

Add this to ~/.claude.json under mcpServers:

"branch": {
  "type": "stdio",
  "command": "branch-mcp",
  "env": { "BRANCH_VIEWER_URL": "http://localhost:7432" }
}

Restart Claude Code. From inside any CC session you'll have 13 tools:

• branch_think({ prompt, model? }) — externalize Claude's own reasoning as a tree. Returns viewer URL.
• branch_fork({ sessionId, nodeId, modifier }) — fork from any node in an existing session.
• branch_inject({ sessionId, nodeId, fact }) — inject a new fact at a node and re-reason from there.
• branch_list_sessions({ limit? }) — recent trees.
• branch_search({ query, limit? }) — full-text search acr