# Orchestration: how to run multiple agents

> A decision guide for running multiple agents: your agent's own subagents, anoint or Ruler for one orchestrator, court for a standing lead, crystl quest for peers, Deus for meta-orchestration across every project.

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](/blog/claude-code-subagents-best-practices/) 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](/blog/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](/docs/agent-antigravity/) worker to check the result, or send the mechanical jobs to an [open model on your own hardware](/docs/open-models/). You pick one agent and every worker is that agent.

In the four crystl approaches below, every worker is a [shard](/docs/gems-and-shards/) 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](/agents/) 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](/docs/fanout/) instead. An [anointed](/docs/cli/#anoint) shard or a summoned [Ruler](/library/heroes/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.

```bash
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`](/docs/cli/#anoint) and [the Ruler](/library/heroes/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.

```bash
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](/docs/court/) 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."

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

Use the [Quest Master](/docs/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](/docs/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](/blog/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.

```bash
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](/library/heroes/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`](/docs/cli/#anoint) or [Ruler](/library/heroes/ruler/) | One gem |
| A standing lead you talk to, separate from the dispatcher | [`crystl court`](/docs/court/) | One gem |
| A fixed team coordinating as peers, no lead | [crystl quest](/docs/crystl-quest/) | One gem |
| Watching and routing work across every open project (meta-orchestration) | [Deus](/library/heroes/deus/) | Every gem |

For the marketing-page overview of orchestration in crystl, see the [orchestration feature page](/features/orchestration/). For exact command syntax and flags, see the [CLI reference](/docs/cli/).

---
Source: https://crystl.dev/docs/orchestration-guide/