Choragos is a small kit that lets one careful AI coordinate several isolated, reviewable coding jobs.
Think of a conductor leading an orchestra. The repo is named for the leader of a Greek chorus. One careful, expensive AI plans the work, writes precise instructions, and checks the results.
Several cheaper AIs each do one small job in their own isolated copy of the code. They follow a written plan instead of guessing what the whole project needs.
A human approves anything risky. The conductor gets the work reviewed before it is accepted, so speed does not remove judgment.
- The
choragoscommand uses the requiredherdrworkspace manager, which supplies isolated workspaces and panes, to check setup, start units, inspect gates, and clean up. - The advice channel is a durable inbox for questions, answers, and completion reports, so a busy AI does not lose a message.
- The approval relay puts a blocked permission prompt in front of a human and sends only the decision that human approved.
- The docs explain the roles, setup, daily loop, safety traps, and a real case study.
- The executor and orchestrator directives bind sessions to the kit's contracts.
Clone the kit and put its launcher on your PATH, which is the list of places your shell searches for commands:
git clone <kit-repository> <kit-directory>
ln -s <kit-directory>/bin/choragos <user-bin-directory>/choragos
export PATH="<user-bin-directory>:$PATH"Run choragos skill-install; invoking the installed skill binds the session as the orchestrator and runs the kit's scoped-work loop.
Write a real squad map. Copy the example, replace every angle-bracket value with an approved harness executable, instructions path, and model selection, then point the launcher at it:
cp <kit-directory>/reference/squads.example.yaml <squad-map>
export CHORAGOS_SQUADS="<squad-map>"From inside any target repository, check the installation and create one unit:
cd <target-repository>
choragos isolation-check
choragos doctor
choragos spec <unit-slug>Edit the new spec with the unit's objective, acceptance criteria, and verification commands. Then run the unit loop from the orchestrator pane:
choragos dispatch <unit-slug>
choragos gates
choragos drain
choragos clean <unit-slug>dispatch creates an isolated worktree and starts the executor. gates shows units waiting for a decision. drain reads your durable advice inbox. Review and merge the unit before clean retires its worktree and spec.
This is for teams with several bounded coding jobs, a repository that needs review, and a human who can handle the few risky decisions. It is less useful for a tiny change or a task whose requirements cannot be written down clearly. See when-to-use.md for a quick fit check.
- Executors follow a written spec exactly and stop when they are confused.
- Nothing automated ever answers a permission prompt for a human.
- Everything is reviewed before merge.
- Read the praxis.md, architecture.md, failure-modes.md, setup.md, operating.md, and case-study.md and the refactor-fleet case study docs for the full rulebook.
A sharp research prototype with genuinely good ideas, not a product. Read it for the design; don't deploy it as-is.
What it is. ~2,300 lines, two-thirds documentation, ~900 lines of bash. One expensive AI orchestrates; cheap executors each get one spec, one git worktree, one pane; a human gates risky actions. Built by its own pattern in one session, with measured token accounting.
What's genuinely good
- The three core mechanisms are correct and hard-won: durable maildir spool with lossy "nudge" delivery (the right model for turn-based agents that swallow mid-turn input), a fingerprinted approval relay that re-verifies the live dialog and never sends bare Enter, and strict one-unit-one-worktree isolation.
- failure-modes.md is observed-in-production, not theorized.
- The case study is honest, including against itself: the orchestrator out-spent its executors 5:1, attribution limits are flagged, and the comparison was pre-registered.
What to worry about
- Hard-wired to herdr, a niche terminal workspace manager. The adoption ceiling is roughly "people running the author's stack." Not portable to CI or headless use.
- Fragile substrate: driving TUIs by keystroke,
sleep-based races with re-sent Enter, a hand-rolled awk YAML parser. The comments admit each hack was "seen live" — honesty about symptoms, but the disease is the transport. - No tests, no CI for the kit itself (only the experiment artifact has tests).
- n=1 evidence. One session, one controlled comparison, one author. The economics claim is plausible but unproven at team scale.
- Bus factor of one, with idiosyncratic vocabulary (praxis, squads, gates) raising onboarding cost.
Recommendation. Treat it as a design document with a working demo. The pattern — spec-driven decomposition, durable async messaging, human-gated side effects, review-before-merge — transfers directly to harness-native mechanisms (subagent APIs, headless dispatch). The plumbing shouldn't. To make it travel, decouple from herdr and add a test harness, in that order.
Choragos runs beside an existing installation without touching it: its state, specs, messages, and plugin namespace are kept separate, and choragos isolation-check proves that the resolved paths do not overlap before work begins.