---
title: Swarms — give a goal to a lead agent that runs a team of workers
---
# Swarms — give a goal to a lead agent that runs a team of workers

## What it is

A **swarm** is a lead AI session plus a pool of worker sessions, all driving at one goal
you write in plain English. You give it a goal, a worker cap and a dollar budget; it works
out what needs doing and puts agents on it.

Unlike everything else in Omniscio that runs several agents, you do **not** author the
steps:

| | What you supply |
| --- | --- |
| **Recipes** | every step, in advance |
| **Bake-Off** | one prompt, fired at many targets once |
| **Gauntlet Loop** | one goal, several competing attempts at the same artifact |
| **Session Refill** | a number of sessions to keep alive |
| **Swarm** | **a goal — it decides the work** |

Swarms are **in development and off by default.** Turn them on at **Settings → Lab**
(`swarmEnabled`).

## Where to find it

### Where it lives

**Inside the Overseers hub, under the Overseer that owns it.** Swarms and Overseers are one
system: a swarm is nested under its Overseer in the hub's list, and selecting it opens the swarm's
own screen — **Overview** (goal, owner, workers against the cap, spend against the budget),
**Workers**, **Chat** with the lead, **Board**, **Queue** and **Settings** (an **About** card for the
name and goal, a **Limits** card for the worker cap and daily budget; a Save bar pinned to the
bottom appears only while something is unsaved). Pause, resume and stop sit in the screen's header,
under a status line such as "Running · 3 of 4 workers · run by Night watch" — on a phone it leaves
out the "run by" part, since the breadcrumb right above already names the Overseer.
Which Overseer owns it follows from the project the swarm runs in, so you never assign it by
hand; if any of its workers is waiting on you, that shows in the Overseer's count too.

You start one from the hub's **New** wizard (*A swarm*: goal, where, limits, review), or hand the
goal to the owning Overseer with *Ask the Overseer to size it instead*. From the command line,
`POST /swarm/create` proposes one behind an approval card.

There is no separate Swarms row in the sidebar any more — the earlier standalone panel was
retired on 2026-09-07 so there is exactly one door. Turning the feature on (Settings → Lab,
`swarmEnabled`) lets the wizard start swarms; while it is off the hub still shows any swarm that
already exists.

The lead and its workers are sessions like any other, but they do **not** get their own project
row: they carry the `__swarm__:<id>` source and are reached through the hub.

## How it behaves

### How it works

1. **You create a swarm** — a name, a goal, a project, a worker cap (default 3) and a
   daily budget (default $10).
2. **The lead plans.** It breaks the goal into a queue of independent work items and picks
   an **angle** for each: builder, critic, researcher, integrator or fixer. The same goal
   gets attacked from different directions instead of by five identical agents.
3. **The tick drains the queue** — once a minute, while there is room under the cap and
   budget, it starts one worker on the next item. An item leaves the queue only after its
   worker starts successfully, so a temporary spawn failure cannot lose work.
4. **Workers coordinate** on a shared board and can message each other directly.
5. **Each finished worker produces a lesson.** The lead reviews what happened, records
   whether it shipped, failed or was abandoned, and writes down what would make the next
   worker do better.
6. **Every future worker is briefed with those lessons**, so the tenth worker starts
   smarter than the first.
7. **When the goal is met** the swarm stops and drops one card in your inbox. It is not
   deleted — the goal and the board stay so you can read what happened.

The lead marks the goal complete with `POST /swarm/:swarmId/complete`. Omniscio accepts
that call only from the swarm's own lead. Repeating it is safe: completion, queue cleanup,
and the inbox notification happen once.

### The board, and who sees what

The posts themselves now live on the **shared agent board** alongside every other kind of agent message (the Stage 2 fold-in, 2026-09-08), on channels named `swarm:<swarm-id>/<channel>`. Nothing changes for a worker or for you: the same commands work, the same clearance rules apply, and a post is still only readable by members at or above its level. It simply means the Overseers hub can show a swarm's board next to everything else that was said, instead of reading a separate store.

Workers coordinate on a **local message board** — channels, kept on your machine, free and
offline. (Team Chat is not used: it bills per message and is your team's human chat, which
eight chattering agents would flood.) **Direct messages between agents already exist** and
are reused as-is.

Every post carries one of three visibility levels, and every agent has a clearance the lead
assigns and can change:

| Level | Who sees it |
| --- | --- |
| **open** | every agent in the swarm |
| **team** | agents at team level and above |
| **lead** | the lead only |

Three rules make this trustworthy rather than decorative:

- **Being on the swarm comes first.** Clearance decides how much of the board an agent sees;
  belonging to the swarm at all decides whether it sees any of it. An agent that was never
  added to this swarm cannot read a single post or write one, and it is told the board simply
  is not there — so it cannot even learn the swarm exists by being refused.
- **A worker can never be given lead-level visibility.** It can ask, and the lead is an AI
  that might be talked round — so the ceiling is enforced in code, where persuasion cannot
  reach it. Only you create a lead-clearance member.
- **When in doubt, it shows less.** A member whose clearance cannot be established sees the
  least, never the most.

### Tools a swarm builds for itself

A worker that finds itself doing something repeatedly can **write a tool**, and the next
worker simply has it. It does that with `POST /swarm/:swarmId/tools` (the name must be
lowercase letters, digits and `-`), and the brief every later session receives lists what
is in the box under **Available swarm tools**.

Those tools stay **inside the swarm**. They are deliberately *not* installed into your
global skills folder, because anything there loads into every session on your machine and
one wrong tool would break your own unrelated work. When a swarm proves a tool is good, you
**promote it to a real skill yourself** — the agent proposes, you decide.

### What stops it running away

Seven independent limits, because a swarm spends money on purpose:

1. **Its daily budget** — at the ceiling, no new workers start.
2. **The shared Overseer ceiling** — one daily budget covering the Overseer and every
   swarm it runs, together. **Off by default: there is no limit unless you set one.** Set it in
   Settings and everything the Overseer runs draws from that single figure; when the day's total
   reaches it, no new workers start and the Overseer stops waking until local midnight, then
   picks up again on its own.
3. **Its worker cap** — never more than N at once.
4. **Your global daily spend cap** — applies to every worker, automatically.
5. **Your approve-before-AI-spawn setting**, if you have it on.
6. **A failure streak** — after several workers fail in a row the swarm pauses itself and
   tells you, instead of burning the rest of the budget.
7. **Pause**, per swarm, plus the master off switch.

If the budget figure itself can't be read, the swarm treats that as **out of money** and
stops — a database hiccup is exactly when a runaway loop would be racking up charges.

The shared ceiling behaves the same way, and it is deliberately NOT the same thing as the
Overseer's runaway-spend alarm. That alarm watches for a sudden *spike* against how much the
Overseer normally costs on its own; a swarm running several workers is far more expensive than
that by design, so counting swarm spending into it would trip the alarm every ordinary hour.
The ceiling is shared; the spike alarm stays on the Overseer alone.

### When things go wrong

A broken swarm always does **less**, never more:

- A lead that is dead, paused or still starting up starts no workers.
- An unreadable instruction from the lead produces **no** worker rather than one with a
  garbled brief.
- Planning and spawn failures wait progressively longer before retrying. After three
  orchestration failures the swarm pauses and tells you why.
- A worker that gets stuck is stopped on a deadline and its slot freed, so one parked agent
  can't jam the pool.
- After a restart the swarm adopts the workers already running instead of duplicating them.
- A failed stop keeps the swarm paused and supervised instead of deleting its record while
  a lead or worker may still be alive.
- Each swarm is serviced independently, so a slow or broken swarm cannot delay healthy ones.
- Everything it does — every start, stop, visibility change, lesson and tool — is written to
  the audit trail with a reason.

The swarm's screen in the hub shows its queued work on **Queue**, and a swarm that paused itself
says why at the top of its **Overview** (*Why it paused*). Those values come from the backend, so
the screen reports the same state that controls whether workers can start.

### What's coming

v1 is the worker pool. Still to come: **Overseer mesh** (several Overseers sharing findings
over the same board) and **Overseer self-improvement** — which will always *propose* changes
for you to accept, never quietly rewrite its own instructions.

## Related

- [overseers.md](overseers.md) — the always-alive watcher a swarm sits beside, and the one hub both are reached from
- [.claude/memory/contracts/swarm-contract.md](/.claude/memory/contracts/swarm-contract.md) —
  the invariants and the tests that lock them