choragos

README

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.

Why Choragos?

• 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 with choragos 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. Set budget = "5.00" on a role to be notified, or have it paused, the moment its session cost crosses the cap. After the run, choragos report summarizes 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), and prefix+p freezes 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_allow on a role to switch it to an allowlist (baseline vars like PATH/HOME/TERM plus the names or PREFIX_* patterns you list), or env_deny to strip specific variables, so a reviewer never sees your AWS_* 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's command). See the threat model.

Guardrails: trust the run, not the agent

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-flow

See 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.

Architecture

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]

Quick Start

Prerequisites

• Go 1.26+
• Supported CLI agents installed (e.g. claude, agy)
• Sphragis installed in PATH (optional, for compliance routing and token telemetry)

Installation

Via Homebrew (macOS / Linux):

brew install sphragis-oss/sphragis/choragos

Prefer 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

Usage

# 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 report

Choragos 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.

Documentation

• Keybindings - the full keymap and window-manager modes
• Configuration reference - every .choragos.toml key, 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 doctor for 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

Configuration & Roles

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.

Development

• 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.

Contributing

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.

Community

• Code of Conduct
• Governance
• Maintainers
• Adopters

License

Licensed under the Apache 2.0 License.