Omniscio

Swarms — give a goal to a lead agent that runs a team of workers

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 — swarms are part of Overseers, available whenever Overseers is on.

On this page

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 part of Overseers: they are available whenever Overseers is on (Settings → Lab), and there is no separate Swarm switch. Turn Overseers off and every swarm stops; your swarms are kept and pick up again when Overseers comes back on.

Not to be confused with an Overseer's crew swarm — several workers started at once on the SAME problem, optionally sharing a private board (agent-crews.md).

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 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. Since 2026-10-08 swarms have no switch of their own either: the Overseers switch turns the hub, the wizard and every running swarm on and off together, so a swarm started from the wizard always runs.

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). Optionally also choose what the workers run on, in either of two forms: a worker model tier (genius, smart, worker or basic), or an explicit worker engine and model (workerProvider plus workerModel) so a swarm's workers can run somewhere other than the app's default engine. Every worker then starts on whatever that choice means at that moment, so a cheaper choice stretches the daily budget over more workers. Leave both out and workers use the app's default engine and model, exactly as before. It is set from the command line (POST /swarm, PATCH /swarm/:swarmId); the swarm screen does not show it yet. A change applies to the next worker only, and if a choice can't be started on this machine the swarm pauses and says so rather than quietly using a different engine or model.
    • The two forms are alternatives: naming both a tier and an engine is refused, because they choose the same thing and a silent winner would make the swarm's own config a lie.
    • opencode is the one engine refused for workers: its sessions cannot reach the swarm's own board, so a worker on it could do the work but never report what it found.
    • The lead always stays on the app's default engine, so its planning is unaffected.
  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.
    • The swarm asks the lead for this list behind the scenes, and the lead answers in a machine format meant for the swarm, not for you. That answer — and the lead's verdict on each finished worker — is hidden from the lead's chat and never puts the lead in your inbox. Anything the lead writes TO you, or a question it asks you, still shows. While the lead is waiting for your answer, the swarm holds its questions to the lead until you reply, so your question stays in your inbox exactly as the lead left it.
  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.

A long post carries its own summary. Like every other board, a post over 200 characters must come with a short TL;DR written by the agent that posted it, or it is refused. The other agents are told about a new post with that summary in hand, so most never need to open the full post. A summary is shown only to agents allowed to read the post itself.

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.

What counts as spend. The budget and the shared ceiling count everything the swarm's sessions spent today: the lead's and workers' own turns plus any charge billed to those sessions. A cost recorded in two places counts once, and a worker you delete still counts. Until 2026-10-01 both read only a separate charge log that session turns never write to, so they stayed near $0 and could not stop a swarm.

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.
  • A lead or worker that has been closed counts as gone, even if its last turn left it waiting for an answer: it holds no slot and is never asked about again. Until 2026-10-20 such a worker kept its slot forever, so the swarm sat at its cap and asked its lead for a paid lesson about once a minute.
  • 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.
  • Asking the lead waits for the lead's own turn to end (up to 10 minutes) and reads its whole reply, however long. Until 2026-10-01 the reply was read before the lead had answered, so a healthy lead looked silent and swarms paused themselves after three asks.
  • The ask counts the turn as ended when the lead has answered, even if the lead stays busy waiting on its own background work afterwards. On 2026-10-06 a lead answered [] three times while waiting on its builders, and the swarm still paused, because the answers were never read.
  • When a swarm pauses because it could not get work, the reason says which part failed: the question never reached the lead, or the lead was asked and gave no answer.
  • 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.

  • overseers.md — the always-alive watcher a swarm sits beside, and the one hub both are reached from
  • swarm-contract.md — the invariants and the tests that lock them

Last verified 2026-10-08