Getting Started • Contributing • Get In Touch
Choragos is a multi-agent development orchestrator. You define the team in a single config file, the roles, the CLI agent each one runs, and the model behind it, and choragos runs the chorus: owned PTY panes per agent, a delegate/work-done protocol over a local socket, human and machine gates, write-owned coordination files, checkpoints, and live telemetry. It can also route every agent's LLM traffic through Sphragis, an EU AI Act compliance gateway, for local PII redaction and a tamper-evident audit log. The gateway is optional: choragos works standalone, and every feature degrades cleanly without it.
The name is the Greek χορηγός (choragos), the one who led and funded the chorus. Here it leads a chorus of agents.
- Owned PTY panes: Choragos spawns each agent in a pseudo-terminal it owns and parses (
hinshun/vt10x), so it knows real input readiness instead of polling a status that lies. This removes the boot races that plague multiplexer-driven orchestrators. - Delegate/work-done protocol: The orchestrator agent hands work to workers via a local UNIX socket with
choragos delegate --to <role> --task "..."; workers report back withchoragos work-done. - Sphragis in the data path, fail-closed when you ask for it: With the gateway enabled, every worker is launched with its LLM base URL pointed at a local Sphragis gateway, and delegation is refused while it is down. When you never asked for it and it is not installed, the deck simply runs with the gateway off and says so.
- Live token and cost telemetry: With the gateway in the path, each role's status card shows its model and live token counts, and dollar cost once you set a
[pricing]table. No SDK hooks, no vendor lock: the gateway counts what the provider reports. Setbudget = "5.00"on a role to be notified, or have it paused, the moment its session cost crosses the cap. After the run,choragos reportsummarizes tasks, durations, token burn, and cost per role from the event log. - Runtime control: Per-role delegation timeouts catch a worker stuck in a loop (
timeout = "45m", notify or restart), andprefix+pfreezes a role (SIGSTOP) so you can inspect its work mid-flight and resume without losing the agent's context. - Least privilege per role (opt-in): By default roles inherit the parent environment. Set
env_allowon a role to switch it to an allowlist (baseline vars likePATH/HOME/TERMplus the names orPREFIX_*patterns you list), orenv_denyto strip specific variables, so a reviewer never sees yourAWS_*credentials. Choragos is not a sandbox: agents run as your user, and OS-level isolation composes from outside (containers, VMs, a wrapper as the role'scommand). See the threat model.
Multi-agent teams fail in a predictable way: an agent gets tired of the task and declares victory, approves its own work, or quietly rewrites the shared state everyone else plans against. Choragos ships a stack of guardrails aimed at exactly that. Each one is opt-in, fails closed to a human, and changes nothing when unconfigured.
| Guardrail | Config | What it stops |
|---|---|---|
| Human gate | approve = true |
a delegation running before a human has seen the plan |
| Check gate | check = "go test ./..." |
work that does not build or pass its tests reaching anyone; the command's exit code is the oracle, a failure comes back to the worker with the output, and the judge only sees work that already passes |
| Judge loop | judge = "reviewer" |
work accepted on the worker's own word; a second model scores it and retries with the critique |
| Write ownership | owns_files = ["defects.md"] |
a role editing coordination state it does not own, e.g. a coder closing its own bugs |
| Worktrees + merge gate | worktree = true, merge = "gate" |
agent changes landing on your branch before a human pages the diff; roles trampling each other's files |
| Checkpoints | on by default in git repos | a bad delegation you cannot undo; every task and merge snapshots the workspace first |
| Timeouts and budgets | timeout = "45m", budget = "5.00" |
a worker stuck in a loop, or a session burning money unwatched |
They compose. In the defects-flow template the coder implements, an adversary hunts for breakage, and QA is the sole writer of defects.md: the coder cannot mark its own bug closed, and the orchestrator cannot report success while the ledger holds an open defect. A change to an owned file by anyone else is detected at the next work-done and held at a human gate, with the audit trail in the event log.
choragos init --template defects-flow
# or the same team with coder and adversary in isolated worktrees and a merge gate
choragos init --template worktree-flowSee teams.md for how each guardrail works, design-check-gate.md for the check contract, design-write-ownership.md for the ownership contract, and design-role-worktrees.md for worktree isolation and the merge gate.
Picking the right stack for a task is its own judgment call: parallel writers need worktrees and ownership, a wide blast radius needs the merge gate and a human, a long unattended run needs budgets and timeouts. The repo ships a Claude Code project skill, choragos-config, that walks those questions, starts from the nearest template, and lets choragos doctor decide when the config is right. It loads automatically when you open the repo in Claude Code; copy the directory into your own project to use it there.
graph TD
User([User]) -->|Tasks| Deck[Choragos Deck TUI]
Deck <-->|Unix Socket IPC| IPC
subgraph Agents
Orchestrator[Orchestrator Agent]
Coder[Coder Agent]
Reviewer[Reviewer Agent]
end
Deck -->|PTY| Orchestrator
Deck -->|PTY| Coder
Deck -->|PTY| Reviewer
Orchestrator -->|delegate| IPC
Coder -->|work-done| IPC
Reviewer -->|work-done| IPC
Orchestrator -.->|LLM Traffic| Sphragis
Coder -.->|LLM Traffic| Sphragis
Reviewer -.->|LLM Traffic| Sphragis
Sphragis[Sphragis Gateway] -.->|Redacted| Anthropic[Upstream APIs]
- Go 1.26+
- Supported CLI agents installed (e.g.
claude,agy) - Sphragis installed in PATH (optional, for compliance routing and token telemetry)
Via Homebrew (macOS / Linux):
brew install sphragis-oss/sphragis/choragosPrefer a GUI? Choragos Desktop is a native macOS app with the matching CLI bundled inside, no terminal needed:
brew install --cask sphragis-oss/sphragis/choragos-desktop(or grab the .dmg from the desktop/v* releases)
Or from source:
git clone https://github.com/sphragis-oss/choragos.git
cd choragos
make build# Write a starter .choragos.toml (roles, keybindings, UI options)
./choragos init
# Or start from a team template: starter, claude-team, mixed-team, review, defects-flow, worktree-flow
./choragos init --template review
# Or let it detect the project (go.mod, package.json, Cargo.toml, pyproject.toml,
# main.tf or terragrunt.hcl, Chart.yaml or charts/*/) and write a team with
# language-specific roles; Terraform and Helm teams gate work on validate or helm unittest
./choragos init --auto
# Start the TUI
./choragos serve
# After a run: per-role tasks, durations, and token usage
./choragos reportChoragos will start the agents and, when Sphragis is installed or explicitly enabled, start the gateway and route all traffic through it automatically; otherwise it runs standalone with the gateway off.
The deck is a tiling window manager over the role panes, driven tmux-style behind a prefix key (default ctrl+b): split (v, -), move focus (h/j/k/l, 1..9), zoom (z), live resize (r), restart a role (R), pause/resume a role (p), broadcast input to all agents (a), task board (t), scrollback search (/), and a help overlay (?). Closing a tile never kills its agent, the mouse focuses tiles and scrolls history, and the terminal bell rings when an agent blocks waiting for input. All bindings are configurable under [keys] in .choragos.toml.
Sessions detach like tmux does: choragos serve --detach runs the crew headless, choragos attach brings the TUI back with screens, tasks, gates, and layout restored, and prefix+d leaves the agents running when you go. choragos ls and choragos kill manage sessions across projects. Quitting is not the end either: choragos serve --resume restores a stopped session's board, gates, and layout, and choragos handoff ends a session with an orchestrator-written handoff document that briefs the next one, optionally under a new team config.
- Keybindings - the full keymap and window-manager modes
- Configuration reference - every
.choragos.tomlkey, including per-role env isolation - Building your own team - roles, per-role models, briefs, and a worked pipeline example
- choragos-config skill - a Claude Code skill that composes a team for a task from the nearest template and validates it with
choragos doctor - Control protocol - the delegate/work-done wire contract for integrators
- Troubleshooting - and run
choragos doctorfor automated checks - Long-running sessions - native detach/attach, resume after a quit, and session handoff
- Sandboxing recipes - wrapping roles or the whole deck in Docker, bubblewrap, or sandbox-exec
- Verifying releases - cosign signatures, checksums, provenance
The team is completely configurable via .choragos.toml. The default team looks like this:
| Role | Default agent | Job |
|---|---|---|
| orchestrator | claude (opus) | plans and delegates, never implements |
| coder | claude (opus) | implements changes |
| reviewer | agy (Gemini) | reviews diffs, reports only |
| auditor | claude (sonnet) | security audit, reports only |
| release | claude (haiku) | runs the release flow after human sign-off |
Every role's agent binary and model is user-overridable.
make build: Build the binary.make demo: Run the UI with placeholder cat panes (with Sphragis off).make test: Run tests with the race detector.
We welcome contributions! Please see CONTRIBUTING.md for details on how to set up your dev environment, formatting rules, and PR guidelines. Note that this project requires a Developer Certificate of Origin (DCO) sign-off on every commit.
Licensed under the Apache 2.0 License.