Orchestration: how to run multiple agents

There are five ways to run multiple agents, and they solve different problems. One of them you already have. This page starts from your situation, not the feature list, and points you at the one to use.

“my agent can already spawn its own agents”

Then start there. Claude Code ships subagents and agent teams, Codex and Antigravity CLI have their own versions of the same idea, and all of them work. One agent splits the task, spawns workers, and reports back.

Here is where it stops. The workers run inside the lead agent’s session, so you never see them. You get the lead’s summary of what happened, not the work. You cannot open a worker’s terminal, read its third tool call, or type a correction into it. When one heads down the wrong path, you find out once it hands you the result. Catching a wrong turn in minute three instead of minute forty is most of what supervising agents buys you. How many agents can you run covers why that makes built-in subagents good at reading and worse at writing.

They are also one agent all the way down. Claude Code’s subagents are Claude Code, and Codex’s are Codex. There is no way to put a Codex worker under a Claude Code lead, add an Antigravity CLI worker to check the result, or send the mechanical jobs to an open model on your own hardware. You pick one agent and every worker is that agent.

In the four crystl approaches below, every worker is a shard you can open. Same fan-out, except you can watch a worker, type into it, approve its prompt, and read its diff before it merges. Any CLI agent runs in a shard, so you fill out your roster with whichever ones you want, mixed in the same fan-out. Try the built-in version first if you never have. Come back when you want to see the workers.

The words matter when you ask. Your agent knows fan out on its own, so “fan this out” may get you the built-in version above. Ask for “fanout shards” and it uses crystl’s fanout instead. An anointed shard or a summoned Ruler needs less steering, because the orchestrator briefing already tells it to coordinate other agents.

“I have one task I want an agent to break up and run for me”

Use anoint or Ruler. Both put one agent in charge of a fan-out: it splits the work, spawns isolated workers, watches them, and merges their branches. Neither adds a conversational lead on top — the orchestrator is the agent you talk to.

crystl anoint                       # confer the role on a shard you're already in
crystl hero summon ruler --gem myapp   # or summon a hero that arrives pre-anointed

anoint hands an existing shard the orchestrator briefing by hand. hero summon ruler gets you the same seat in one step, for a fresh shard, with no separate crystl anoint call and no gap before it can dispatch. Pick anoint when you’re already talking to the agent that should run the fan-out; pick Ruler when you know up front that a gem needs an orchestrator and want it summoned ready to go.

See crystl anoint and the Ruler for the details.

“I want a standing lead I talk to, with a separate agent doing the dispatching”

Use court. A court seats two agents instead of one: the crown is the shard you talk to, and the hand is its orchestrator. The crown holds no work, so it’s never busy when you want to talk to it — everything you’d otherwise wait behind goes to the hand instead.

crystl court "ship the 3.0 release"

This is the standing version of the anoint/Ruler seat: same orchestrator role, sitting behind a conversational lead instead of being the agent you address directly. Use it when a fan-out is going to run long enough, or often enough, that you don’t want to be talking to the same agent that’s also mid-task.

See Court: the crown and the hand for the full breakdown, including standing officers with persistent remits.

“I want a fixed team of specialists coordinating as peers, no lead”

Use crystl quest. A quest is deliberately flat: a party of heroes with names, roles, and personalities coordinate in a shared chat panel, no agent is in charge of the others, and you watch and steer with mentions. Where anoint/Ruler/court all report up to one agent, quest doesn’t have an “up.”

crystl quest start --gem myapp --party "Design & Dev"

Use the Quest Master to plan a staged questline from a goal first, if the work has real sequential phases rather than one open-ended room.

See crystl quest for parties, chat, and open vs. sealed mode.

“I’m running agents across multiple projects and want one place to see what’s blocked anywhere”

Use Deus. This is the meta-orchestration layer, sometimes called super-orchestration: Deus orchestrates the orchestrators rather than the work. Every role above is scoped to one gem — the orchestrator runs that gem’s workers, the crown and hand are seated together in that gem’s court. Deus is the one role that isn’t: it surveys every open gem, sorts what it finds into working, finished, blocked on you, or broken, and turns anything blocked into one decision set instead of a project-by-project chase.

crystl hero summon deus

Deus never orchestrates a single project’s work itself — when a gem already has a Ruler or an anointed agent running, it hands that gem’s work to them rather than dispatching into it directly. It owns no codebase and writes no code, not a line, not a fix, not a merge.

See Deus for the full role.

The shape of it

Your situation	What to use	Scope
Finding out whether you need any of this	your agent’s own subagents	Inside one session
One task, one agent to run the fan-out	crystl anoint or Ruler	One gem
A standing lead you talk to, separate from the dispatcher	crystl court	One gem
A fixed team coordinating as peers, no lead	crystl quest	One gem
Watching and routing work across every open project (meta-orchestration)	Deus	Every gem

For the marketing-page overview of orchestration in crystl, see the orchestration feature page. For exact command syntax and flags, see the CLI reference.