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 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.

A long post carries its own summary. Like every other board, a post over 1,000 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.

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 — the always-alive watcher a swarm sits beside, and the one hub both are reached from
• .claude/memory/contracts/swarm-contract.md — the invariants and the tests that lock them