Branch

Give your AI agent the memory of your entire system.

Branch is an open-source command center for multi-repo development. It runs in Claude Code and gives your agent the memory of every repo, every API contract, every deploy dependency. Optionally pair with OpenAI Codex CLI for adversarial second opinions on reviews and gap checks.

Get started in 60 seconds

npx @branch-computer/branch init

This launches Claude Code in a Branch workspace, auto-discovers your repos, scans every codebase, and builds your command center. Confirm which repos to include and you're done.

Prerequisites

• Claude Code installed and authenticated — required
• GitHub CLI (gh) installed and authenticated
• Git 2.x+
• Optional: Codex CLI for second-opinion reviews via /codex and post-scan gap checks

What happens when you run /start

CONNECT                                              STEP 1 / 5
================================================================
Organization: your-org (detected from GitHub)
Sources connected:
  ✓ GitHub org (42 repos found)
  ✓ Local repos (~/code — 12 repos found)

SELECT REPOS                                         STEP 2 / 5
================================================================
  [x]  1. api-gateway          TypeScript    CI ✓  CD ✓
  [x]  2. user-service         Go            CI ✓
  [x]  3. web-app              React         CI ✓  CD ✓
  [ ]  4. deprecated-tool      Python        CI ✗

SCANNING                                             STEP 3 / 5
================================================================
  [1/3] api-gateway ............ done
  [2/3] user-service ........... done
  [3/3] web-app ................ done

YOU'RE OPERATIONAL                                   STEP 5 / 5
================================================================
  3 repos    5 interfaces    5 agents    18 commands

  Try: /plan-feature, /deploy-check, /repo-sync

Why this exists

| Without Branch | With Branch | |------------------|---------------| | "Add notifications" — Claude modifies one repo, breaks the API contract with two others | /plan-feature maps the change across all repos, sequences the work, flags deploy order | | Deploy backend before shared types are published — runtime crash | /deploy-check catches the dependency and reorders the steps | | New hire asks "how does auth work?" — 45 min of grep across 6 repos | cross-repo-researcher traces the full auth flow in seconds | | PR review misses that a schema change requires a worker update | architecture-validator flags the cross-repo violation automatically | | Three repos have no CI — nobody notices until prod breaks | /ci-scaffold generates GitHub Actions from the repo's actual build system |

Commands

Every command maps to a stage of the development cycle. Run /start after setup to see the full menu.

Think

| Command | What it does | |---------|--------------| | /plan-ceo-review | Challenge premises, rethink the problem, find the 10-star version. Three modes: expand scope, hold scope, reduce scope. |

Plan

| Command | What it does | |---------|--------------| | /plan-feature | Cross-repo feature decomposition. Reads your full architecture, searches existing code to avoid duplication, produces a repo impact matrix and deploy order. | | /plan-eng-review | Lock the execution plan. Architecture, data flow, edge cases, test coverage, performance — with opinionated recommendations. |

Frontend

| Command | What it does | |---------|--------------| | /frontend-audit | Scan a frontend codebase — design patterns, components, styling, state management. | | /plan-ui | Plan a UI feature — component breakdown, state, API integration, accessibility, responsive. | | /design-system | Audit or create a design system — tokens, component inventory, architecture. |

Build

| Command | What it does | |---------|--------------| | /add-service | Plan full integration of a new service — infra, data, CI/CD, docs. Respects the deploy dependency graph. | | /add-integration | Wire in a 3rd-party API — research the SDK, design the client, map data, define error handling. | | /onboard-repo | Add a repo after initial setup. Same deep scan as onboarding. |

Review

| Command | What it does | |---------|--------------| | /b-review | Check the work. Routes to code, security, simplify, design, QA, or Codex review. | | /simplify | Review changed code for reuse, quality, and efficiency — then fix what it finds. | | /security-review | OWASP Top 10, secrets scan, dependency audit, cross-repo trust boundary analysis. |

Test

Powered by gstack — a fast headless browser extension for AI agent CLIs.

| Command | What it does | |---------|--------------| | /qa | Systematic QA with a real browser. Full, quick (30s smoke test), or regression mode. Health score + structured report. | | /browse | Headless browser — navigate, click, fill, screenshot, assert. ~100ms per command. |

Ship

| Command | What it does | |---------|--------------| | /b-ship | Get it out there. Routes to pre-flight, land, canary, or release docs. | | /deploy-check | Deployment coordinator. Dependency analysis, pre-checks, step-by-step plan with rollback. | | /ci-scaffold | Generate GitHub Actions from the repo's actual build system. Node, Python, Go, Rust, Terraform. |

Reflect

| Command | What it does | |---------|--------------| | /retro | Weekly retrospective. Commit history, work patterns, code quality. Per-person breakdown with trends. | | /repo-sync | Detect drift between orchestration docs and reality. Propose updates. |

Communicate

| Command | What it does | |---------|--------------| | /create-deck | Publication-ready HTML presentation with Chart.js visualizations. Single file, no dependencies. |

Agents

Agents activate automatically — you don't invoke them. Your AI agent delegates to them when the situation matches.

| Agent | When it triggers | What it does | |-------|-----------------|--------------| | cross-repo-researcher | Questions spanning multiple repos | Traces code and data flows across repo boundaries | | architecture-validator | PR reviews, code changes | Catches interface contract violations and deploy order issues | | pr-reviewer | Code review requests | Reviews for security, correctness, cross-repo impact | | incident-investigator | Production errors, downtime | Debugs across the service topology | | doc-sync-checker | Doc staleness concerns | Verifies orchestration docs match actual code |

CLI

Run directly with npx — no clone needed:

npx @branch-computer/branch <command>

| Command | What it does | |---------|--------------| | branch init | Create a project and launch the interactive setup | | branch status | Show active project and knowledge graph stats | | branch mcp | Start the MCP server (used by agent integrations below) | | branch scan | Re-scan repos (delegates to /setup in your agent CLI) | | branch help | Show help |

MCP Server

The MCP server gives any AI agent instant architecture awareness. After running /setup to generate your knowledge graph:

# Add to Claude Code
claude mcp add branch -- npx @branch-computer/branch mcp

# Or if you cloned the repo
claude mcp add branch -- node mcp-server/index.js

Tools

| Tool | What it does | |------|--------------| | get_repo_topology | Full system topology — repos, dependencies, deploy order, interfaces | | get_interfaces | Interfaces for a specific repo | | get_deploy_order | Correct deployment sequence | | get_conventions | Stack-wide conventions | | detect_drift | Check for knowledge staleness | | validate_change | Validate a proposed change against architecture constraints |

Resources

| Resource | What it provides | |----------|-----------------| | branch://architecture | Full architecture as background context |

Multi-project support

Branch supports multiple projects from a single install. Each project is an independent workspace with its own architecture docs, memory, and repo set.

/start                  # Create a new project or switch between existing ones

Projects live in projects/<name>/ (gitignored) and are fully isolated from each other.

Agent runtime support

Branch runs in Claude Code. OpenAI Codex CLI is optional and used for adversarial second opinions via /codex and post-scan gap checks.

| Tool | Role | Install | |------|------|---------| | Claude Code | Required primary driver | npm i -g @anthropic-ai/claude-code | | OpenAI Codex CLI | Optional second opinion | npm i -g @openai/codex |

Claude Code is required on startup. Codex is auto-detected only to enable second-opinion reviews and gap checks.

Optional: Browser skills (gstack)

The /qa, /browse, /b-review, /b-ship, and /retro commands use a headless browser powered by gstack. Install once:

git submodule update --init --recursive
cd .claude/skills/gstack && ./setup

Requires Bun v1.0+. Everything else works without this step.

How it works under the hood

Branch generates three key files per project from your codebase scan:

| File | Purpose | |------|---------| | SYSTEM_ARCHITECTURE.md | Single source of truth — every repo, service, API, data flow, and deploy dependency | | CLAUDE.md | Context file loaded automatically by the AI agent — repo map, interfaces, constraints, conventions | | docs/REPO_SETUP.md | Where to find repos on any machine — makes the setup portable across team members |

When you run a command like /plan-feature:

1. The agent reads the full architecture (automatic via CLAUDE.md)
2. Resolves repo paths from REPO_SETUP.md
3. Searches existing code across all repos (avoids duplication)
4. Validates against architecture constraints (avoids violations)
5. Produces a plan respecting deploy dependency order

Customization

Add a command — Create .claude/commands/your-command.md. See examples/command.example.md.

Add an agent — Create .claude/agents/your-agent.md with YAML frontmatter. See examples/agent.example.md.

Troubleshooting

/start can't find my repos — Set REPOS_ROOT to the parent directory:

export REPOS_ROOT=~/code

Docs say "empty" after setup — Run /start to trigger the scan.

Agents not triggering — Verify files exist in .claude/agents/ with valid YAML frontmatter.

Browser skills unavailable — Run git submodule update --init --recursive && cd .claude/skills/gstack && ./setup

Docs drift after changes — Run /repo-sync to detect and fix.

License

MIT