orchestrator

# Orchestrator

> Provider-agnostic CLI that turns a tmux window into an AI agent team — a
> lead agent delegates to Claude Code / Codex / Grok / Gemini CLI teammates
> (or any CLI taught via a [providers.custom.*] config block) as labeled
> tmux panes — and routes each task to whichever of the user's
> subscriptions has the most quota left right now (headroom routing).
> Headless dispatch with JSON results, exact-session follow-ups, a git
> worktree per teammate with a `land` step to merge work back, teammate
> busy/needs-input/idle detection, verified teardown, and a roster that
> survives reboots (`resurrect`). Single-file Python, stdlib only;
> macOS/Linux (WSL runs as Linux); requires tmux and at least one
> signed-in provider CLI. Current release: v0.5.4.

Key facts: commands exit 0 (success), 1 (operational failure), 2
(precondition error, e.g. not inside tmux), 3 (internal refusal with a
reason). Teammate states: active / busy / needs-input / idle (interactive)
and running / done / failed(N) / died (dispatch). Provider states: ready /
quiet / locked out / not installed / unknown. `list`, `status`,
`providers`, `usage`, `worktree list`, `land --dry-run`, and
`resurrect --dry-run` accept `--json`. Core rule: Orchestrator refuses instead
of guessing — exact session or refusal, keep-and-report instead of
discarding work, unknown stated as unknown. It never reads or stores
credentials — it drives the official vendor CLIs under the user's own
logins.

## Docs

- [Agent operating guide](docs/AGENT_GUIDE.md): canonical machine-oriented reference — exact command syntax, exit codes, state vocabulary, handoff protocol, worktree/land lifecycle, deterministic recovery recipes, custom-provider schema, the lead-agent operating rules verbatim
- [Install instructions for agents](INSTALL.md): the canonical fetch-and-follow install flow (verify with `orchestrator doctor`)
- [Complete guide](docs/GUIDE.md): every feature in depth, full configuration reference, security posture, FAQ, honest limitations
- [README](README.md): the short human-oriented overview + install
- [Use-case recipes](docs/use-cases.md): worked workflows with exact commands and expected on-screen output

## Optional

- [Installer/setup design spec](docs/design/installer-spec.md): the express init and custom cockpit UX contract
- [Recording harness](docs/recordings/README.md): how the README demos are reproducibly re-rendered