The operating system for AI coding agents. One supervised interface, many coding agents.

Orchestra dispatches coding-agent CLIs (Claude Code, OpenCode, Mimo, …) through one supervised interface. You just chat: it answers plain questions, routes coding tasks to the best agent, validates every result (build → lint → test), lets the agent fix its own failures, and keeps nothing without your y. It can decompose a big request into steps — running independent ones in parallel, each isolated in its own git worktree (or folder copy outside a repo) — remembers every run, and can benchmark agents against each other.

# install (Linux/macOS) — prebuilt binary
curl -fsSL https://raw.githubusercontent.com/crossben/orchestra-code/main/install.sh | sh

# …or with Go (any platform)
go install github.com/crossben/orchestra-code/cmd/orchestra@latest

# …or build from source
git clone https://github.com/crossben/orchestra-code && cd orchestra-code
go build -o bin/orchestra ./cmd/orchestra

Windows: download the .zip from Releases, or use go install. If orchestra isn't found after install, add the bin dir to your PATH (the installer prints the exact line).

cd /your/project           # any git repo, clean working tree
orchestra                  # interactive chat shell (AI-routed)
orchestra dashboard        # full-screen TUI (agents / history / benchmarks / chat)
orchestra run "add a /health endpoint" --test "go test ./..."

Requirements: Go 1.22+, git, and at least one agent CLI on your PATH (claude, opencode, mimo, …). Add your own agent in one config block — see docs/EXTENDING.md. Roadmap and design notes in plan.md; contributions welcome — CONTRIBUTING.md.

Two ways to use it — same engine underneath:

Interactive shell (the primary UX)

orchestra            # drops you into a chat session

orchestra (auto) › what does this repo's config loader do?
  … routing
  <answered inline — no agent dispatched>

orchestra (auto) › add a /health endpoint
  ↳ implement → agent "opencode" (code change)
  … agent runs, tests run, diff shown …
  accept these changes? [y/N] y
  ✓ changes accepted and committed

orchestra (auto) › @claude write tests for it   # force one task to a specific agent
orchestra (auto) › /route off                   # fall back to a fixed active agent
orchestra (claude) › /exit

The AI router is on by default: plain questions are answered inline, coding tasks auto-route to the best agent (with a printed reason). The agent is chosen by: the AI's own suggestion → the agent with the best track record in this directory (accepted runs + benchmark wins, once there are ≥3 outcomes; e.g. claude: 8/10 accepted in this dir) → router.routes → default_agent. Overrides: @<name> <task> forces an agent; /route off switches to a fixed active agent (/agent <name>). Shell commands: /agents, /route [on|off], /agent, /help, /exit. Each accepted turn is committed, so the tree stays clean and every turn's diff shows only its own changes.

One-shot (scriptable, for CI/workflows)

orchestra run "add a /health endpoint" --agent claude --test "go test ./..."

Plans & sequential workflows

Decompose a large request into ordered steps, then execute them one at a time — you approve the plan first, then review each step's diff:

orchestra plan "build user authentication"   # just show the decomposition
orchestra do   "build user authentication"   # plan → approve → run each step, commit as you go

do commits each accepted step and halts at the first rejected step (prior steps stay committed).

Parallel (--parallel): the planner marks which steps are independent; Orchestra runs each ready step concurrently in its own git worktree (or, in a folder that isn't a git repository, its own temporary copy of the folder), then you review + merge each result before the next dependency wave unlocks:

orchestra do --parallel --jobs 4 "build the API, the CLI, and the docs"

Independent steps run at once; dependent steps wait for their prerequisites to merge. Each accepted branch is merged into the base with conflict detection (a conflicting merge is left unmerged and its dependents are skipped); rejected branches are discarded. The base working tree is never touched during execution — all work happens in isolated worktrees.

Outside a git repository the copies are made with the same ignore rules as snapshot diffs (dependency and build directories such as node_modules, vendor, dist are not copied), and an accepted step's files are written back only if none of them changed in your folder since the step started — otherwise the step is reported as a conflict and nothing of it is written. The check is per file: two steps editing the same file conflict even if they touched different lines. Copies are deleted when the run ends.

Memory & history

Every run is recorded in ~/.orchestra/orchestra.db (outside your repo, so it never dirties the tree):

orchestra history        # recent runs for this project + the agent you accept most
orchestra history --all  # across all projects

Dashboard (TUI)

A full-screen dashboard where you send tasks, watch agents work, and review their changes:

orchestra dashboard      # or: orchestra dash

It opens on Chat. Type a task (enter sends, ctrl+j adds a newline) and a live run panel shows routing, each attempt, the agent's output as it streams, and every validation stage (build → lint → test) as it passes or fails. Failed checks retry automatically. esc cancels a run and reverts whatever the agent already changed. The panel sits beside the chat on wide terminals and stacks below it on narrow ones.

When the agent is done you get a review screen: a file list with +/− counts, the selected file's diff, validation badges, and the failing check's output if there is one. [ / ] move between files, a shows all files, ↑↓ scrolls, then y accepts (commits in a git repo) or n rejects (reverts). With the AI router enabled, each message is routed to the best agent, and plain questions are answered inline.

Parallel runs. Start a message with /parallel (or /par) to run it like orchestra do --parallel:

/parallel add a login page, a signup page, and tests for both

The default agent plans the request into steps with dependencies, then each wave of independent steps runs concurrently (up to 4 at a time), every step in its own isolated tree — a git worktree inside a repository, a folder copy in a plain folder — so nothing touches your files yet. The run panel becomes a task list: one row per step with its status (queued, running, validating, retrying, done, failed), agent, attempt, elapsed time and last output line. ↑↓ / j k select a task, enter or tab expands its full output, esc collapses (and esc on the list cancels the run). When a wave finishes, every step that changed something opens in the same review screen, headed wave i/N · task k/M: y merges it into your folder, n discards it. A merge conflict with work already merged is reported and counts as a rejection; failed steps are shown with their error and skipped, and steps that depend on a rejected or failed one are skipped too. Then the next wave starts. ctrl+c mid-run cancels every task, removes every isolated tree and undoes any stray write into your folder before quitting. Each step is recorded in History like a single run.

The other tabs:

• Changes: every diff you accepted or rejected. Reopen any of them with enter, even after a restart.
• History: all runs with outcome, attempts and checks.
• Agents: installed, live probe, runs, accept rate and last use.
• Benchmarks: past leaderboards.
• Logs: this session's events.

Keys: tab / 1–6 switch tabs (digits outside Chat), r refresh, q quit (outside Chat), ctrl+c quit. Colors adapt to light and dark terminals.

Benchmark agents

Run the same task through every agent (each isolated in its own worktree — or folder copy outside a git repository — in parallel) and rank them:

orchestra benchmark "add input validation to the login form"
orchestra benchmark "..." --agents claude,mimo   # limit which agents

Produces a leaderboard sorted by validation → fewer retries → faster → smaller diff, then offers to merge the winner into your base tree. Results are recorded to memory (benchmarks table) to feed future data-driven routing. (Token/cost columns are deferred — agent CLIs don't report usage generically.)

Prove the lean-code effect — run each agent twice (principles off vs on) and see how much smaller the diff gets:

orchestra benchmark "add a settings page" --compare            # off vs full
orchestra benchmark "..." --compare --principles lite          # off vs lite

AGENT   VALID off/on  ±off   ±on   Δlines  Δ%
claude  ✓/✓           +80-10 +41-3 -46     -51%
▸ -47% fewer changed lines overall

How it works (supervised loop)

1. Dispatch the agent CLI in headless, auto-approve mode, streaming its output live.
2. Validate by running the pipeline (build → lint → test, stop at the first failure). Checks are auto-detected from the project (Go, Node, Rust, Python, or plain JS) when none are configured — only checks whose toolchain is installed are run, so a missing tool never causes a false failure.
3. Self-correct — if a check fails, feed the failure back to the agent and let it retry in place, up to max_retries times, so you review a result that already builds and passes tests when possible.
4. Review — show the git diff + per-stage validation report and ask you to accept or reject.
5. Accept keeps the changes (the shell commits them); reject restores the tree exactly.

Auto-approve is deliberate: Orchestra's diff review is the human gate, so agents must not block on their own permission prompts. Agents are also told to proceed on reasonable assumptions rather than ask questions (there's no interactive channel in headless mode). If an agent responds without editing anything, Orchestra detects it and — when the response looks like a question — prompts you to refine your request and retry, instead of silently reporting "nothing to review".

Lean-code principles. Every task is prefixed with a configurable simplicity-first preamble (reuse before adding, no needless deps/abstractions, no unrequested features) so any agent writes smaller, cleaner changes — agent-agnostic, at the orchestration layer. Set principles: off|lite|full in config, or override per run with --principles. (Default lite.)

Requirements

• Go 1.22+
• git (the accept/reject loop is built on it)
• At least one agent CLI on your PATH (claude, opencode, codex, or gemini)
• A clean working tree to start (reject reverts the tree). run accepts --force.

Build & run

go build -o bin/orchestra ./cmd/orchestra
./bin/orchestra                 # interactive shell
./bin/orchestra agents          # list agents + availability
./bin/orchestra init            # write a starter orchestra.yaml

Updating

Release builds check GitHub for a newer version at most once a day when started in an interactive terminal, and ask Download and install now? [Y/n]. On yes, Orchestra downloads the archive for your platform, verifies its SHA-256 against the release's checksums.txt, replaces its own executable, and exits — relaunch to use the new version. Run orchestra update to check on demand (--check to only report, -y to skip the prompt).

The check never runs in pipes, scripts or CI (CI set), for dev/snapshot builds, or when ORCHESTRA_NO_UPDATE_CHECK=1. Installed via Homebrew/Scoop or into a directory you can't write to? Update the same way you installed instead.

Configuration

Orchestra works with no config (built-in defaults for the common agents). To customize, orchestra init writes an orchestra.yaml:

default_agent: claude
timeout: 10m
principles: lite          # lean-code preamble injected into every task: off | lite | full

# Validation pipeline — each result must pass before you review it. Leave stages
# empty to auto-detect checks from the project; set them to override, or auto:false
# to disable. On failure the agent retries with the output, up to max_retries.
validate:
  build: "go build ./..."   # or leave empty to auto-detect
  lint:  "go vet ./..."
  test:  "go test ./..."
  auto:  true
max_retries: 2

# AI router — reads each message, answers questions, routes tasks to an agent.
router:
  enabled: true
  agent: claude          # who classifies / answers
  routes:                # static fallback: intent → agent
    plan: claude
    implement: opencode
    review: claude
  # Optional: classify with a cheap hosted model over HTTP instead of spawning the
  # router agent's CLI. Used only when the key env var is set; otherwise Orchestra
  # quietly falls back to `agent` above (which still answers plain questions).
  # classifier:
  #   provider: anthropic      # openai (default) | anthropic
  #   model: claude-haiku-4-5
  #   api_base: ""             # optional endpoint override
  #   api_key_env: ""          # optional; defaults to ANTHROPIC_API_KEY / OPENAI_API_KEY

agents:
  - name: claude
    bin: claude
    args: ["-p", "--dangerously-skip-permissions"]
    capabilities: [plan, implement, review]
  - name: opencode
    bin: opencode
    args: ["run", "--dangerously-skip-permissions"]
    dir_flag: "--dir"   # for CLIs that ignore process cwd — required for parallel worktree isolation
    capabilities: [implement, review]
  - name: mimo
    bin: mimo
    args: ["run", "--dangerously-skip-permissions"]
    capabilities: [implement, review]

dir_flag tells Orchestra how to pass an agent its working directory. Most CLIs honor the process cwd, but some (e.g. opencode) don't — set dir_flag so parallel worktrees (and folder copies) stay isolated. Orchestra also guards the base tree: if an agent writes outside its worktree anyway, the stray changes are discarded before merge so one misbehaving agent can't break the wave.

A config file overrides defaults and adds agents; matching names replace the built-in entry.

Commands & flags

Command	Purpose
orchestra	interactive chat shell with AI routing (default)
orchestra run	one-shot task dispatch
orchestra plan	decompose a request into ordered steps (no coding)
orchestra do	plan + execute steps (sequential, or --parallel)
orchestra dashboard	full-screen TUI: agents (live probe), history, benchmarks
orchestra benchmark	run one task through every agent, ranked leaderboard
orchestra history	recent runs + preferred agent
orchestra agents	list agents; --probe live-tests each can actually run
orchestra init	write a starter orchestra.yaml
orchestra update	install the latest release; --check only reports, -y skips the prompt

run flags: --agent, --test, --retries, --timeout, --force. do: --agent, --yes, --parallel, --jobs. Global: --dir.

Architecture

cmd/orchestra        Cobra CLI: run / plan / do / history / agents / init / shell (default)
internal/agent       Agent interface + CLIAgent/APIAgent + registry + Querier
internal/config      YAML config + built-in agent defaults + validator auto-detection
internal/fsdiff      git-free supervision: dir snapshots + unified diff + restore
internal/llm         HTTP LLM providers (openai-compatible, anthropic) behind one interface
internal/patch       extract changes from model replies and apply them safely
internal/ui          terminal styling: gradient banner, spinners, colored diffs (TTY-aware)
internal/tui         Bubble Tea dashboard: agents / history / benchmarks (read-only monitor)
internal/router      AI routing: Classifier (agent CLI or direct API) → Decision, tiered fallback
internal/planner     decompose a request into ordered steps (+ depends_on for parallel)
internal/scheduler   bounded-concurrency runner + DAG waves (cycle/blocked detection)
internal/parallel    shared parallel workflow pieces (step graph, base-tree guard, quiet per-task run) ← do --parallel, dashboard /parallel
internal/worktree    task isolation: git worktrees in a repo, folder copies elsewhere; merge + conflict detection
internal/engine      supervised pipeline (dispatch → validate → retry → review) + headless mode  ← run/shell/do
internal/shell       interactive chat REPL
internal/memory      SQLite run history + preferred-agent hint (~/.orchestra)
internal/runner      generic process exec (stream / capture / timeout)               ← the engine's engine
internal/validate    build → lint → test pipeline, stop-on-first-failure
internal/gitutil     is-repo / is-clean / diff / restore / commit
internal/review      show the diff, prompt accept/reject

runner runs a process; agent says which command each agent is; engine is the supervised loop every front door (run, shell, do) drives; planner + do add multi-step workflows; router picks the agent; scheduler + worktree add parallel dependency waves; memory records it all. Next (M6): benchmark mode, context engine, plugin SDK, and the full Bubble Tea dashboard.