banyan

Banyan's mental model is small but specific. Five concepts cover everything.

Project

A group of repos that ship together. Examples:

frontend + backend + mobile app + infra stack
a Lerna-style multi-package codebase (one banyan "repo" per package)

Projects are declared in ~/.config/banyan/config.yaml. Each project has a name and a list of repos.

Repo

A single git repository (or a type: compose docker-compose definition that's not actually git). Each repo has:

a path (where its main checkout lives)
a base branch (what to rebase / merge against)
a run config (command + port + env)
optional: copyOnWorktree, loadEnvFiles, hooks

Feature

A unit of work that gets:

One git branch (feature/<name>) checked out as a worktree in every repo
One Claude agent pane with --add-dir on every worktree
One docker compose stack per compose-type repo, on dynamically-allocated host ports
One tmux test window (one pane per repo running its run command)

Features live in parallel. Banyan ensures none of them step on each other.

Worktree

A git worktree-managed checkout, separate from the main checkout. Layout:

~/Documents/Dev/MyApp/
  Front/                       ← main checkout
  worktree-Front/
    login/                     ← worktree for feature "login"
    payment/                   ← worktree for feature "payment"
  Back/
  worktree-Back/
    login/
    payment/

Each worktree is fully independent: you can have Front/worktree-Front/login running on port 3001, Front/worktree-Front/payment on 3002, both pointing at their own backend on 8081 / 8082.

Agent

A Claude Code instance running in a tmux pane with --add-dir on every repo's worktree for a feature. Has the banyan MCP server wired in. Conversations resume across reboots via claude --continue.

Four agent modes:

interactive — plain Claude, you drive
assisted — agent asks on big decisions
autonomous — agent decides everything
autopilot — autonomous + loops on Stop hook until banyan_report_done

Orchestrator

A second Claude agent that lives above the features. Has:

--add-dir on every repo
The banyan MCP server (can dispatch tasks to per-feature agents, predict conflicts, drive merges)

The orchestrator is launched automatically by bn <project> start. It sees everything; per-feature agents only see their feature.

Concepts