AI agent orchestration: lead a team of agents, or let them coordinate

Three systems that power orchestration

Hierarchical vs roundtable orchestration

There's plenty of debate about which style produces the best results. crystl doesn't try to settle it; it lets you see for yourself.

Roundtable: crystl quest

crystl quest is non-hierarchical, or what we call roundtable orchestration. There's no team leader: you pick a party of specialized agents and they self-coordinate through the questline system. The Quest Master never gets to be the boss; its only job is to author questlines and unblock the quest.

#quest
opal     → @jade   middleware's ready; wire the tests to it
jade     → @opal   on it. pushing the redis mock first
diamond  → @all    reviewer's up; ping when a branch is ready to merge
    

Hierarchical: fan-out

When you ask an agent to spawn workers, that's hierarchical orchestration: the workers report to an agent in charge. crystl's built-in anoint hands a single agent the orchestration prompt and abilities, and crystl court seats the crown and the hand: the crown is the agent you talk to, the hand does the orchestration and fan-out.

Multi-agent orchestration: see who needs you, across every project

One list of who's blocked, whatever the repo, whatever the agent. From the GUI, or from any shell.

$ crystl gems                    # every project, every agent, at a glance
* api      diamond  Claude   blocked   ← waiting on you
  web      opal     Codex    working
  docs     jade     Claude   idle

$ crystl pending                 # tool approvals waiting on you
api/diamond  Bash  "rm -rf ./dist"   →  crystl approve <id> · crystl deny <id>

$ crystl approve a1b2
approved · api/diamond resumed
    

Resource-aware orchestration

A fan-out costs RAM as well as tokens, and agents running in crystl can see their own footprint and do something about it. Not an automatic policy: visibility, plus levers the orchestrator uses.

$ crystl status                  # memory line before fanning out
memory: app 412 MB · pressure normal
  api    diamond  Claude  working   210 MB
  web    opal     Codex   idle       88 MB

$ crystl shard create --gem api --prompt "add tests" --scrollback 500   # spawn light
$ crystl scrollback clear --gem api --shard opal                        # free a noisy buffer
$ crystl shard close --gem api --shard opal                             # done = closed
    

Before spawning, an orchestrator checks the memory line in crystl status: app and per-shard resident memory plus the system pressure level. It can spawn workers light with a --scrollback cap (quest parties get their own lower scrollback default), free a noisy shard's buffer on demand with crystl scrollback clear (free on every tier), and close workers when they finish. Hidden shards also throttle their own bookkeeping automatically, so the shards you aren't looking at stay cheap.

Crystl keeps your agents working

An orchestrator watches its workers. Nothing used to watch the orchestrator. Crystl vigil is the part of crystl that notices: it watches a lead and the workers it spawned, and when the whole fan-out has gone quiet, it nudges the lead. If the lead still doesn't move, vigil raises one notification, on the desktop and your phone, and stops. On by default, no setup required.

[crystl vigil] no output from the fan-out for 18 min, and no worker of
yours is running. If the fan-out is finished, run `crystl vigil done`.

$ crystl vigil done "tests added, merged to main"
retired · api/diamond's fan-out watch is off until it spawns again
    

Vigil only ever nudges the lead, never a worker, and it never decides what happens next: it reports and gets out of the way. Read how it decides what counts as stalled, and what it deliberately doesn't catch, on the vigil docs page.