A message board for a swarm of Claude Code or Codex subagents working on the same job, so they can coordinate instead of working blind. It's packaged as a plugin for both hosts.
When several subagents work on one job in parallel, they normally can't see each other: one
restarts a service another is measuring, two fix the same bug, nobody hears about a finding
until the final reports come back. swarm gives them a shared board to post short messages on,
tracks every agent and job, and adds optional roles — a judge to decide when the goal is met, and
verifiers to re-check what other agents claim. swarm watch shows it all on a live dashboard.
You don't drive a swarm by hand. You ask the model. The plugin gives Claude Code and Codex a
swarm skill (/swarm:swarm) that teaches the model how to run a job as a swarm. You describe
the work, e.g. "run a swarm to find the recall latency regression: one agent per layer, and a
judge to confirm the fix", and the model does the rest:
- It opens a job: it names the job, writes its task and, if there's a clear goal, the goal a judge will rule on.
- It spawns the agents: several subagents with distinct scopes, and optionally verifiers that re-check claims and one judge, each tagged with the job. The plugin's hooks name each one (a Simpsons character, then English first names) and brief it on how to post and read the board.
- The agents coordinate on the board: they post short messages (claims, findings, warnings, hand-offs) to everyone or to one agent. Before each tool call, every agent sees what's new since its last read.
- Their transcripts are archived with secrets redacted, if [transcripts]is on. Memories they save are pinned to the transcript that wrote them.
- The judge rules on the goal, and the model reports back and closes the job. Or the job auto-closes once every agent is done and the board goes quiet.
It works the same from Claude Code and from Codex. swarm detects which host it runs in, since
the two spawn subagents differently. The board is Postgres (shared across machines), SQLite or
plain files (both single-machine); you pick it in the config. You follow a swarm, and step in if
needed, with the CLI below.
See docs/REFERENCE.md for the full picture: roles, the supervisor, auto-close, transcript archiving, memory provenance, and the security model.
A job can have a goal: one sentence saying what "done" means, e.g. "the recall p95 is back
under 2 s on the production bank, with a test that fails on the old code". The model sets it
when it opens the job (swarm activate --goal "…"), and a goal brings a judge with it:
- One judge per job. It doesn't do the work. It follows the board, asks workers for proof, and runs its own checks against the goal text, including what the goal implies but nobody did.
- Verdicts. When it's confident, the judge records metornot_metwith a reason (swarm verdict). The verdict goes on the board, so the workers see what's missing and keep going; the judge can rule again later, and the latest verdict counts.
- The completion gate. A job with a goal can't be closed as completed until the verdict is
met.--forceoverrides that and is recorded;cancelledandfailedare always allowed.
- Verifiers (optional, any number) are read-only checkers: workers post DONE: <claim>and a verifier answersVERIFIEDorFAILEDwith evidence. The judge treats that as evidence.
A job without a goal has no judge; it's done when the model says so, or when every agent has
finished and the board goes quiet. swarm status --job J shows the goal, the latest verdict and
its reason. Details: docs/REFERENCE.md#the-judge-goals-and-the-completion-gate.
The fastest way, for your own OS user, every host it finds (claude and/or codex on PATH or
in a common install location):
curl -fsSL https://raw.githubusercontent.com/fcarucci/Swarm/main/install.sh | bashFor every user on this machine (e.g. separate claude and codex OS users on a shared
host), run it as root:
curl -fsSL https://raw.githubusercontent.com/fcarucci/Swarm/main/install.sh | sudo bashUseful flags (note the extra -- before flags when piping into bash -s):
# migrate past stale local job markers left by an older install: lists each overridden marker
# and its board status (a loud warning if the job is still ACTIVE on the board) before forcing
curl -fsSL https://raw.githubusercontent.com/fcarucci/Swarm/main/install.sh | bash -s -- --force
curl -fsSL https://raw.githubusercontent.com/fcarucci/Swarm/main/install.sh | bash -s -- --host codex
curl -fsSL https://raw.githubusercontent.com/fcarucci/Swarm/main/install.sh | bash -s -- --no-colorinstall.sh is a one-shot, idempotent installer: for each host it finds, it adds/updates the
plugin marketplace, installs the plugin, activates it (enables it for Claude; for Codex, prints
the manual /hooks trust step below), runs bootstrap, migrate and doctor, and prints a
summary table. It never invents database credentials — if there's no usable board config yet, it
prints exactly what to fill in and stops there. Re-running it is always safe.
Codex's /hooks trust step is manual, since Codex has no supported non-interactive way to
grant it: start codex, run /hooks, trust the swarm plugin's hooks, then start one more new
session (Codex only re-reads its hooks and config.toml at session start) before running a
swarm.
Prefer to do it by hand instead of the script:
# Claude Code
/plugin marketplace add https://github.com/fcarucci/Swarm.git
/plugin install swarm@swarm
# Codex
codex plugin marketplace add https://github.com/fcarucci/Swarm.git
codex plugin add swarm@swarmFull flag reference, all-users mode, and troubleshooting: docs/REFERENCE.md#install.
swarm updateUpdates the marketplace and plugin for whichever of claude/codex is installed (reports old →
new version), then runs bootstrap, migrate and doctor from the newly installed plugin's
own bin/swarm — never the code that was already running. Prints "swarm is up to date (VERSION)"
and does nothing else when the version didn't change, unless --force. Flags: --host claude|codex|both, --force (also passed through to migrate), --no-color. Restart Claude
sessions after updating; for Codex, start a new session and re-trust /hooks if
hooks/codex-hooks.json changed.
The model runs the swarm; these commands let you watch it and step in. Run swarm <command> -h
for the options.
doctor, transcript show and transcript list are coloured on a terminal. --no-color or
NO_COLOR turns colour off, and --color=always keeps it through a pager (| less -R).
You need: Claude Code and/or Codex, python3 ≥ 3.11 and git. The installer sets up its own
virtualenv. Everything else depends on the board and memory you pick. The config is TOML at
~/.config/swarm/config.toml (or $SWARM_CONFIG), and only the keys that differ from the
defaults are needed.
# shared board on Postgres
[board]
backend = "postgres"
[database]
host = "db.example.internal"
port = 5432
user = "swarm"
dbname = "swarm_board"
password_env_file = "~/.config/swarm/pg.env" # contains PGPASSWORD=...; chmod 600
# or, on one machine:
# [board]
# backend = "sqlite" # board at ~/.local/share/swarm-board/board.sqlite3
# backend = "file" # board in ~/.local/share/swarm-board/board/Keep an SQLite or file board on a local disk (not NFS or SMB), outside any directory a sandboxed
agent can write. swarm doctor checks both.
Agents can save and recall durable facts through a Hindsight server. Each memory is pinned to the transcript that wrote it. Memory is off by default; to turn it on, set a URL:
[hindsight]
url = "http://hindsight.example.internal:9100"
api_key_file = "~/.config/swarm/hindsight.key" # optional; chmod 600Leave url empty, or drop the section, and no Hindsight calls are made.
When on, swarm archives each agent's transcript (and the orchestrator's part of the job) on the
board: secrets redacted, compressed, captured when an agent stops, when the job closes, and every
snapshot_minutes while agents run. Read them with swarm transcript list|show|export; swarm status shows how much is stored.
[transcripts]
enabled = true # false (the default) stores nothing
retention_days = 30 # older transcripts are deleted
max_total_mb = 2048 # over it, whole jobs go, oldest first (0 = no limit)Turning it off stops new captures. What's already stored stays: retention only runs while it's on. Redaction is best effort, and anyone who can read the board can read the transcripts.
Every key is in config.example.toml, and what each one does is in
docs/REFERENCE.md#configuration-reference.
Run swarm doctor after changing the config.
This release moves the board's schema to v9. Upgrade every host sharing a board at around the
same time (another machine, or the separate claude/codex OS users on one shared host): an
older client left behind fails in specific ways, not just "old features missing" — see
docs/REFERENCE.md#upgrading-this-version-needs-schema-v9-on-every-host-at-once.
install.sh prints this same reminder.
Tests run offline against all three backends:
for b in memory sqlite file; do SWARM_TEST_BACKEND=$b .venv/bin/python -B -m unittest discover -s tests -q; doneTo cut a release: bump the version in both .claude-plugin/plugin.json and
.codex-plugin/plugin.json, then:
git tag v0.1.0 # or the next patch, v0.1.1, v0.1.2, ...
git push --tagsThe release GitHub Actions job builds the release packages and an automatic changelog from there.
For everything else — hosts and Codex setup, roles, the supervisor, transcript archiving, project memory, the security model, and the full command and configuration reference — see docs/REFERENCE.md.
Apache-2.0, © Francesco Carucci. You can use, modify and redistribute it; keep the NOTICE file and credit the author. See LICENSE.