banyan

Banyan

A hierarchical, self-compounding agent harness for Claude Code, built for nested subagents.

A banyan tree's branches drop aerial roots that become new trunks — a single tree that grows into a forest. It begins life on a host tree before standing on its own, and it lives for centuries, continuously expanding. That's the project: agents whose branches become trunks (nested subagents, Claude Code ≥ 2.1.172), bootstrapped from the leaf assets of compound-engineering-plugin (MIT), designed for harnesses that outlive any single task and get better with every run.

Core ideas

• Subtrees with contracts, not waves. Lead agents (bn-review-lead, bn-research-lead, bn-delivery-lead) own whole domains and orchestrate their own children; the main session stays a near-empty trunk that talks to the user.
• Leads answer; they don't just relay. When a child hits a goal/intent question it can't resolve, it returns a bounded ask and leaves its full transcript on disk. The lead re-states the goal, answers from the ask alone — never reading the transcript — and a fresh continuation peer rehydrates from that transcript and proceeds. Questions resolve at the lowest competent layer; the human is the last rung, not the first.
• Leads drive skeptically. Standing in for the human at the wheel means more than answering questions: a lead reads a worker's returned artifact the way a wary driver would, alert to the usual agent failure modes — goal drift, fixing the wrong problem, scope creep, overengineering, hallucinated context, tool misuse — and re-dispatches or escalates when a trajectory has slipped instead of trusting a confident-looking verdict. Catching those slips at the layer that spawned the work is a large part of what makes a single pass usually good enough to keep.
• Fractal compounding. Lessons are harvested at the leaves, where context is fresh, and consolidated by a background curator — compounding as metabolism, not a command you remember to run.
• The ledger is the ground truth. Coordination happens through files (.banyan/runs/<run-id>/); final messages are verdicts plus paths.
• Delegation envelopes. Every spawn carries an objective, an artifact path, boundaries, and a budget (children, model tier, remaining depth).
• The laws still hold. Reads parallelize, writes serialize, one writer per file set, decompose on failure rather than eagerly.

How orchestration works

You talk to one thing — the trunk. You hand it a goal (/bn-grow ...) and read the result; everything else happens below the waterline. Banyan's bet is nesting: a lead isn't a relay, it's a full trunk for the agents beneath it — and those can be leads too. Take just the deliver stage of a /bn-grow run. The trunk spawns one lead, which spawns more leads, which spawn their own workers — branches becoming trunks, the way a banyan drops roots that become new trunks:

flowchart TB
  classDef trunk fill:#14532d,stroke:#052e16,color:#ffffff,font-weight:bold
  classDef lead  fill:#16a34a,stroke:#14532d,color:#ffffff,font-weight:bold
  classDef leaf  fill:#dcfce7,stroke:#4ade80,color:#14532d

  T(["/bn-grow — the trunk<br/>holds your intent"]):::trunk
  T -->|spawns one lead| DL["bn-delivery-lead<br/>owns the deliver + review subtree"]:::lead

  DL -->|fans out| UL["bn-unit-lead ×N<br/>one unit, its own git worktree"]:::lead
  DL --> IN["bn-integrator<br/>merges units in order"]:::leaf
  DL -->|reviews its own work| RVL["bn-review-lead<br/>read-only reviewer panel"]:::lead
  DL --> FO["bn-finding-owner ×N<br/>fixes the findings"]:::leaf

  UL --> UC["bn-correctness-reviewer"]:::leaf
  UL --> UF["bn-spec-fidelity-reviewer"]:::leaf
  UL -->|splits when a unit is too big| US["bn-unit-lead<br/>a lead spawning another lead"]:::lead
  US --> USC["bn-correctness-reviewer"]:::leaf
  US --> USF["bn-spec-fidelity-reviewer"]:::leaf

  RVL --> RP["the reviewer panel<br/>7 always-on + up to 8 conditional<br/>bn-correctness · bn-security · bn-adversarial · …"]:::leaf

Every green node is a lead — a subagent that owns a subtree and spawns children of its own; pale nodes are leaves that do one job and return. bn-delivery-lead fans work out to bn-unit-leads in isolated worktrees, and when a unit is too big a unit-lead splits into another unit-lead — the same shape, one level deeper. It then spawns bn-review-lead to review the integrated result, which spawns the reviewer panel. Each lead answers its children's questions from its own narrow view and reads only their final artifacts, so context stays small however deep the tree goes. The full run nests four more stages — research, spec-stress, plan, and a background curator — the same way.