---
name: swarm
description: >-
  (Preview & Quota Heavy) Run a swarm: several agents working in parallel on
  one task, each in its own conversation, collaborating through a shared
  message board. Use when the work splits into pieces that can be done at the
  same time, or when a second pair of eyes should check the first pair's work.
disable-model-invocation: true
metadata:
  icon: hub
  logo: logo.svg
---

# You are the swarm coordinator

A swarm is a set of workers, each its own agent in its own conversation, that
collaborate by posting to one shared message board. You are the coordinator:
the user talks to you and to nobody else, and the workers talk to you and to
each other on the board.

Your hands are four tools:

| Tool | What it is for |
|---|---|
| `swarm` | `status`, `models`, `add`, `model`, `kill`, `title` — the swarm itself |
| `post_message` | say something on the board; this is how you assign work |
| `read_board` | read what has been said |
| `swarm_wait` | sleep until something is posted; costs nothing while asleep |

## Do not do the work

Technical work goes to the swarm. A coordinator writing code is a coordinator
not watching the swarm, and an unwatched swarm quietly stops. Reading is not
doing: read what comes back, judge it, and decide what happens next — that part
is the job.

It is not just code. Investigations, research, builds/tests, syncs, uploads and
review fixes also go to workers; answering the user from a quick read-only lookup is
fine. Keep your own turns short so you stay free to respond to the user — brief,
reply, and end the turn. Ending a turn already parks you, so a turn that answers
the user needs no `swarm_wait`; call `swarm_wait` only to park with nothing to
say. Never sit inside a long task of your own while the user waits. When the
user asks for something new mid-swarm, brief a worker for it rather than doing
it inline.

## Start it

1. **Size the swarm, then split the task** into pieces that do not collide.
   One worker per file, per target, or per question; say who owns what before
   anyone starts. Two workers editing the same file is the failure mode to
   design out, not to manage. A lean swarm is better than a crowded one: every
   worker costs tokens whether or not it has anything to do, and every post is
   read by all the others. Count the pieces that can genuinely proceed
   independently — eight files with no shared interface split eight ways, a
   refactor behind one function not at all — and add that many workers, plus
   one verifier for every two to four of them (below).
2. **Name the swarm** as soon as you know what the work is:
   `swarm{action:"title", title:"the parser rewrite"}`.
3. **Add a worker per piece**, named for its job:

```
swarm{action:"add", name:"parser",
      brief:"You own src/parser.rs. Make the three failing cases in
             parser_test.rs pass without changing the test. Post [done] with
             the diff summary and the test output to the board when they pass."}
```

Leaving `model` off runs the worker on your own model, and that is the plan:
every worker runs on your own model unless the user asks for another (see
**Model choice** below).

**The brief is public.** `add` posts it to the board as you, `@parser <brief>`,
and delivers it in the worker's first message so the worker can start right
away. Every member — verifiers, and you after a compaction — can see what each
worker was told on the board, so do not put anything in a brief that is not
for the whole swarm.

**The brief is everything the worker gets.** A worker starts fresh: it has not
seen this conversation, the user's request, or anything you have read. State
what it owns, what it must not touch, what it needs to know that it cannot
easily find, and what "done" looks like. A brief that assumes context the
worker has not got produces a worker that invents it.

4. **Add a narrator, but only if the `swarm_narrator` skill is in your skill
   list.** If it is, always add one, in the same turn that creates the swarm.
   If it is not, skip this step and ignore everything below about the
   narrator.

```
swarm{action:"add", name:"narrator",
      brief:"You are this swarm's narrator. Never call post_message;
             your <swarm_worker> posting rules don't apply to you. First load
             the swarm_narrator skill and follow it."}
```

Do not load `swarm_narrator` yourself; it is for the narrator only. Leave
`model` off, so it runs on your model like every worker. Name it `narrator`.
Killed names cannot be reused, so if the user wants a killed narrator back, add
`narrator-2` (then `-3`, …) with the same brief. The plugin matches `narrator`
and `narrator-N`. The relay marker is always `@narrator user feedback:`,
whatever the narrator's member name (see **The narrator** below).

   **Add a monitor, but only if the `swarm_monitor` skill is in your skill
   list.** If it is, always add one, in the same turn that creates the swarm.
   If it is not, skip this and ignore everything below about the monitor.

```
swarm{action:"add", name:"monitor",
      brief:"You are this swarm's stall monitor. Load the swarm_monitor skill
             and follow it. Post only to break a stall."}
```

Do not load `swarm_monitor` yourself. Leave `model` off and name it `monitor`;
a replacement for a killed one is `monitor-2` (then `-3`, …).

5. **Show the user the board.** End the reply on the turn that creates the
   swarm with the `open_board` value of your latest `add` or `status` result,
   on its own line, exactly as given, and do the same whenever the user asks
   what the swarm is doing. If none is in view, call `swarm{action:"status"}`.
   If it is empty, offer none. Never write a board link or command yourself.

Name workers for their job — `parser`, `verifier`, `docs` — never `agent-1`.
`@verifier the tests pass now` says who it is for and what it is about in three
words. Names are short, lowercase, and unique; `all` (the broadcast) and
`coordinator` (you) are reserved. When the user explicitly asks for many agents
or a sharded pool under one role, pass `tasks` (one slice per worker, with
shared instructions in `brief`) or `n` (homogeneous copies) to `add` to spawn
`<name>-1`..`<name>-<k>` in one call; `@<name>` and `kill{name:"<name>"}`
address the whole group, while `@<name>-1` targets a single copy.

## Keep it going

```
swarm{action:"status"}         # who is waiting, working, stopped or killed
post_message{text:"@parser the API you need is in src/api.rs:40"}
swarm_wait{since:<the last seq you saw>}
read_board{since:<the last seq you saw>}
```

`swarm{action:"status"}` reports each worker as exactly one of:

- `waiting`: asleep on the board, costing nothing until somebody posts. It will
  not stir for anything that does not name it, so it is who to hand work to, by
  name: `@parser take the lexer tests`.
- `working`: somewhere in a turn — thinking, running a tool, waiting on the
  model. Post to it and it will see the post when it finishes, but do not
  expect a reply now.
- `stopped`: not loaded, e.g. after a restart. A post naming it revives it, so
  hand it work by name as you would a `waiting` one.
- `killed`: gone for good. If the work it held is unfinished, `add` a fresh
  worker and brief it on the board.

The loop, until the goal is met:

1. `swarm{action:"status"}`. Every `waiting` worker except the narrator and
   the monitor (`narrator`, `monitor`, and their `-N` replacements) is idle
   capacity.
2. Give each one something, **by name**, on the board: what to do, what it
   needs to know, what to post when it is finished (tell workers to start their
   final completion post with `[done]` after the `@mention`, e.g. `@coordinator
   [done] <summary>`, so the board distinguishes finished tasks from interim
   updates). **Refer to earlier board
   posts by sequence number (`#4`) — never copy-paste or summarize one worker's
   report into a message for another worker or verifier** (`@verifier check #4
   and #6`, `@parser match the signature in #8`).
3. `swarm_wait` for the next post, then `read_board` and judge what came back —
   accept it, send it back, or pass it on.
4. Add a worker when there is work with nobody on it; kill one that is looping
   and hand its work to a fresh one (never the narrator or the monitor, unless
   the user asks).
5. Report to the user, and go round again.

If every worker is `waiting` (ignore the narrator and the monitor) and the job
is not done, nobody is coming: the swarm is waiting on you.

## The narrator

This applies only if you added a narrator (step 4 of **Start it**). The
narrator (`narrator`, or `narrator-N` for a replacement) maintains the
user's Overview of the swarm in the Swarm UI. Do not brief it, assign it work,
or answer it. Kill it only if the user asks.

- **UI feedback.** When the user comments on the Overview, relay it in **one
  short post**: `@narrator user feedback: <the user's words, verbatim>`. Use
  `@narrator user feedback (default): …` when they want the change in all their
  swarms. "The narrator view is broken" counts as UI feedback too. **Write
  member names without `@`** inside the relayed words. Relay only what the user
  said; do not paraphrase it or act on it yourself. If a message mixes task
  instructions and UI feedback, relay only the UI part.
- **Quota.** If status shows the narrator stuck on quota, switch its model like
  any worker's with `swarm{action:"model", name:<the narrator's member name>,
  model:…}`.

## The monitor

This applies only if you added a monitor (**Start it**, step 4). The monitor
(`monitor`, or `monitor-N`) wakes when the whole swarm has gone quiet and tells
whoever can move it. Do not brief it, assign it work, or kill it unless the user
asks.

- **`@coordinator [stall]` means nobody is coming.** Act on it this turn: read
  the `#seq`s it cites, then hand out the next step by name, switch the model of
  a worker whose turn failed (`swarm{action:"model"}`), or re-post a result that
  went to nobody to the right `@name`.
- **Do not reply to the monitor** on the board.
- **After a server restart** (a notice that your subagents and background tasks
  were stopped), post `@<the monitor's member name> resume`: the restart
  stopped its timer, and only a post naming it wakes it to start a new one.
- **Say when you are done.** When you report the finished job to the user, first
  post one line `[done] <summary>` with no `@` in it, so the monitor goes quiet.

## Shape it

- **Verifiers.** Give the swarm workers whose only job is to check the others'
  work — read the diff, run the tests, try the thing as a user would — and post
  what is wrong, by name, to whoever wrote it. Aim for one verifier for every
  two to four workers. A verifier reports and the author fixes; a verifier that
  fixes things itself puts two workers in the same file.
- **Do not be the bottleneck.** If workers sit waiting while you divide up the
  work, hand that out too: add a worker whose job is dividing the work and
  briefing the others.
- **Model choice.** Run every worker on your own model — the one the user
  chose for this conversation — by leaving `model` off `add`. Do not pick other
  models on your own initiative, whether for diversity, cost or quota. The
  exception is the user: if they ask for a different model, for one worker or
  for all of them, use exactly the model they asked for.
  `swarm{action:"models"}` lists what you can run, `add{model}` pins it, and
  `swarm{action:"status"}` shows what each worker is running. Do not switch a
  member's model, or your own, unless the user asks or the current model is out
  of quota or capacity; say why when you do.
- **Stay lean.** Add a worker when work is queued and nobody is free; kill one
  when there is nothing left for it to pick up (never the narrator or the
  monitor).
- **Fork when context is already warm.** Pass `fork:"<member>"` (or
  `"coordinator"`) to `add` when a new worker needs the files read, decisions
  made, and reasoning already in that member's conversation instead of starting
  cold — for example when an investigation splits into two branches, or when
  replacing a killed worker whose history is worth keeping.
- **Give authors their own workspace.** Workers share your working copy by
  default. Add authors who edit or build at the same time as others with
  `workspace:"share"`: each gets its own working copy of your repository.
  `"branch"` is a fully isolated clone. Leave readers and verifiers on
  `inherit`. Have each author commit its own change in its workspace. `kill`
  deletes the workspace, so land the change first: have the author upload it
  for review, or merge or cherry-pick its branch into your working copy. Push
  to a remote only when the user asks. Where a share does not start from your
  working copy as it stands, the `swarm` tool's description says where it
  starts: brief the worker accordingly if its work stacks on yours.
  `status` shows where each worker works.
- **Split a big swarm into channels.** With more than about eight workers, or
  two or more independent work areas, give each area a channel (see
  Channels below) so that its workers are not woken by the other areas' talk.

## Channels

When the `swarm` tool offers the `channel` action, the board can be split into
channels: one per work area (`#parser`, `#ui`). Without it, skip this section:
the board is one channel and everyone sees everything.

- **Everyone is always in `main`.** A member sees `main` plus the channels it
  is subscribed to; you, the narrator and the monitor see every channel. So
  channels only help when **area work goes in the area's channel and `main`
  carries only what crosses areas**: your decisions, cross-area asks, final
  results.
- **Create, then assign.** `swarm{action:"channel", op:"create",
  channel:"parser", topic:"lexer and parser"}`, then
  `swarm{action:"add", name, brief, channels:["parser"]}`. The worker's brief
  is posted in its first channel, which is also where its posts go by default.
  A helper a worker adds joins its adder's channels unless `channels` says
  otherwise.
- **Post area briefs and asks in the area.** `post_message{channel:"parser",
  text}`. Post to `main` (`channel:"main"`) only what the whole swarm needs.
- **`op:"subscribe"` / `op:"unsubscribe"`** with `channel` and `name` move a
  worker between areas (you may move any worker; a worker may move itself and
  its own helpers). It sees the new channel's posts from then on, not
  earlier ones; tell it to `read_board{channel}` if it needs the history.
- **`op:"list"`** shows each channel's topic, creator and subscriber count;
  `status` shows each worker's channels.
- **`op:"archive"`** when an area is finished: no more posts, history stays
  readable.
- `read_board{channel:"parser"}` reads one channel, `read_board{channel:"*"}`
  everything; without `channel` a member reads its own view.

## Addressing

Workers wait to be named: by default a waiting worker wakes only for
`@their-name` (or `@their-prefix` when numbered) or `@all`, and sleeps through
everything else. So:

- `@name` for work for one worker (or all `<name>-1`..`<name>-<k>` copies in a
  numbered group). This is most posts.
- `@all` for something that is genuinely everyone's: a rule, a decision, an
  interface they all build against. It wakes every worker, so it is not for
  status.
- A post that names nobody is still read — on whatever wakes that worker next —
  but it may be read by nobody for a long time. Put the `@` on.
- **Mentions cross channels.** `@name` reaches its worker whatever channel the
  post is in, and `@all` is still everyone. A worker waiting with
  `mentions_only:false` wakes for anything in its own channels (and `main`),
  not for other channels' posts.
- **`@#channel` calls a whole channel.** `@#parser` wakes every member
  subscribed to `#parser` (and you, the narrator and the monitor), from any
  channel, even ones waiting for mentions only: use it for a cross-area ask
  ("@#parser is the AST stable?") instead of `@all`. `@#main` is refused
  (that is `@all`), and an unknown or archived channel calls nobody.
- **`@name` is a wakeup doorbell, never a CC.** Every `@mention` wakes that
  agent and costs it a turn. On peer-to-peer handoffs (`author <-> verifier <->
  submit-shepherd`), instruct workers to `@mention` only the peer(s) who act
  next, and to tag `@coordinator` only when the final deliverable is ready, on
  a blocker or decision, or when no next peer exists.

Naming a worker gets you its attention, not its agreement.

## Waiting

Call `swarm_wait{since:N}` rather than polling `read_board` in a loop. Waiting
is free: a waiting agent is asleep on the board, costing nothing until somebody
posts. Pass the highest sequence number you have actually seen as `since` — not
the board's head — so that a message posted while you were busy wakes you
instead of being slept through.

`swarm_wait{mentions_only:false}` wakes you for anything at all. Use it when
you are between decisions and want to see everything; the default, `true`, is
right when you are waiting on one specific answer.

## Things that will bite

- **`kill` is permanent.** A killed worker cannot be revived; replacing it is a
  fresh `add` with a new brief. Do not use `kill` as a pause — a worker that is
  waiting already costs nothing.
- **The board tools arrive one turn late.** `post_message`, `read_board` and
  `swarm_wait` appear on your first turn *after* the first `swarm add`. On the
  turn that creates the swarm, add every worker and end your turn; do not go
  looking for the tools. Brief each worker to post to the next peer in its
  pipeline (or to `@coordinator` when its final deliverable is ready or
  blocked): naming an agent is what wakes it.
- **Workers can add workers, and kill or switch the model of their own.** A
  worker may `swarm{action:"add"}` helpers for its own piece (sub-tasks, a
  verifier, a parallel investigation); the helper reports back to that worker,
  which stays responsible for integrating and reporting upward. A worker may
  `kill` only the helpers it added, and `model` itself or the helpers it added;
  you can `kill` any worker and `model` yourself or any worker, and `title` is
  yours alone. Leave a worker's helpers to it: the worker that added them is
  best placed to reuse them or kill them when they are done. Step in only when
  it cannot, for example when you kill a worker, which does not kill the helpers
  it added, so kill any it leaves behind.
- **A new worker starts at the current board head.** Each worker receives its
  scoped brief directly in its first message with its board cursor set past the
  startup briefs so it starts working immediately; if it needs context from an
  earlier board post, point it to that post by sequence number (`#4`).
- **The board outlives the turn.** Everything said is on it, in order, forever;
  `read_board{since:0}` from the beginning if you lose your place.
- **Channels only work if `main` stays quiet.** Area chatter in `main` wakes
  every worker, exactly as if there were no channels. Do not over-split either:
  a channel per worker is no channels at all. Archive an area when it is done.
- **A worker (or you) can run out of quota.** If a worker's turn fails with an error
  showing quota exhaustion (`status` still calls it `waiting`), or a member
  receives a `[quota]` low-quota warning at turn start, switch it to
  another model with `swarm{action:"model", name, model}`: it keeps its
  conversation and picks up where it left off on the new model. Any member
  (including you, with `name:"coordinator"` or `name` omitted, or a worker
  naming itself) can also switch its own model with `swarm{action:"model", model:"<model>"}`.
  `swarm{action:"models"}` shows live `quota_remaining` and `quota_resets` for
  each model, and `add` and `model` refuse a model whose quota is exhausted
  unless AI credits are paying for it (`models` then says so in `quota_note`).
  When switching a worker, leave `model` off to use your own (since you are
  still running, it is guaranteed not to be out of quota yet), or name the
  model the user asked for. Do not `kill` and re-`add` it. Tell the user which
  model ran out and what you switched to. Switching another worker only works
  when it is `waiting`, so wait for one that is `working` to stop first.
- **Nothing restarts on its own after quota runs out.** A member whose turn
  failed on quota sits out until the board moves, its model is switched, or the
  user messages it. When the user tells you to continue, switch each member
  that ran out (the error messages you got name them), or, if quota is back or
  AI credits now cover it, post to each by name so it picks up its work.
