run-an-agent-swarm

name	run-an-agent-swarm
category	code
description	Run several coding agents in parallel on one repository from a shared work queue, with per-agent isolation, serialized builds, disk limits, and a supervision loop that reclaims stalled work. Use when someone asks to run a coding swarm, work through open beads overnight, keep several agents moving through a backlog, or stop parallel agents from colliding in one checkout or filling the disk.

run-an-agent-swarm

Running several agents on one repository is a scheduling problem before it is a prompting problem. The output that matters is merged, reviewed, tested changes, so the swarm needs a queue that hands out one item per owner, checkouts that cannot overwrite each other, a build path that does not thrash the machine, and a supervisor that notices when an agent has stopped making progress.

When to use

Use this when the backlog is genuinely parallel, each item can be checked independently, and the repository already builds and tests from a single command. It suits a long unattended run: an audit sweep, a migration across many call sites, a bug queue.

Do not use it for one hard change that needs a single coherent design. Do not use it on a codebase with no test signal, because a swarm with no test signal produces volume that nobody can verify. Do not point it at a repository where a bad merge reaches users directly.

Preconditions

• Read every applicable AGENTS.md file and the repository README.md completely before dispatching work. If either is missing, record that fact instead of inventing its rules.
• An agent-readable architecture note names the entry points, module boundaries, build command, test command, and files agents must not touch. Write it before launch.
• A shared work queue exists outside any single agent's memory. Every item has an id, a statement of done another agent could check, a status, and an owner field.
• The main branch is protected. A human, or a reviewer that did not write the change, approves every merge.
• Measured build cost is known: cold build time, test time, and disk consumed per build.
• Free disk is at least the number of agents multiplied by twice the cold build size.
• No agent checkout can read production credentials. Scope the run to a throwaway environment or to credentials that cannot touch user data.

Roles the swarm needs

Any tool that fills the role works. The roles are what matter.

role	what it must do	examples
work queue	hand out one item per owner, hold status and evidence	a bead tracker such as br and bv, issue tracker, a checked-in queue file
session host	start, list, message, and stop agents without losing their output	a terminal multiplexer such as ntm or tmux
isolation	give each agent a private working directory	git worktrees, one container per agent
build runner	one cached, serialized build and test path for all agents	a shared cached runner such as rch, a remote build cache
supervisor	run the cycle below on a fixed interval	a scheduled loop, a human at a keyboard
model roster	record each worker, runtime, model, and reasoning setting	three Codex workers and three Claude Code workers, or another reviewed mix

Tool mapping

Treat tool names as an implementation of the roles above, not as magic words. When the environment provides ntm, vibing-with-ntm, rch, br, bv, loop, or a named review skill, read that tool's installed instructions before invoking it. Never guess a command from the tool name.

• Map ntm and vibing-with-ntm to session hosting, worker launch, and messaging.
• Map br and bv to queue creation, claim state, stalled-item inspection, and evidence.
• Map rch to the shared build runner. Route every build and test through it when required by the repository, and set one project-level build slot unless measurements justify more.
• Map loop to the supervision cycle. Four minutes is the default interval for an unattended run.
• Map installed testing-* and specialist review skills to the queue-expansion passes used only after open and reclaimed work is exhausted.

If one of these tools is unavailable, name the missing role and propose a substitute. Get approval before changing the requested roster, model, reasoning setting, or work tracker.

Procedure

1. Ground the swarm once. Read every applicable AGENTS.md from the repository root to the working directory, then read README.md completely. Investigate the code and write an architecture summary: purpose, entry points, module boundaries, data flow, build and test commands, and the parts that are risky to change. Every worker receives that note and the original files remain authoritative.
2. Fill the work queue before any agent starts. Split items until one agent can finish one item in one sitting. Anything vague becomes an investigation item that produces a written finding, never a speculative code change.
3. Size the swarm to the build, not to the model budget. Start with the number of agents the disk and build runner can carry, run one full cycle, and add agents only if that cycle stayed green.
4. Record the model roster before launch. Include worker id, runtime, requested model, reasoning setting, and role. Verify that every requested model and setting is actually available; if not, stop and ask before substituting. Use more than one model family when requested because disagreement between them is a useful review signal.
5. Give every agent isolation. One worktree or container per agent, its own branch, no shared working directory. An agent edits only the files its claimed item names.
6. Route every build and test through the shared cached runner and cap how many builds run at once, usually at one per project. Uncontrolled build contention is the common way a swarm turns into a machine that compiles all night and ships nothing.
7. Set a disk budget and enforce it every cycle. Prune stale build artifacts, remove worktrees of finished items, and stop admitting new work below the headroom threshold. The cleaner deletes from a fixed path allowlist. Never let an agent choose a recursive delete target.
8. Publish the claim protocol and require it: claim the item with owner and timestamp, push a branch within the first few minutes, update the item with evidence, release the claim if blocked. An item with no owner is open; an item with an owner is not touched by anyone else.
9. Run the supervision cycle on a fixed interval, four minutes by default. Each cycle: read the queue, hand the next item to any idle agent with fresh instructions, release every stalled claim, reclaim disk, and append one line to the supervision log. Lengthen the interval only when normal units of work cannot produce a heartbeat within it.
10. Treat a claim as stalled when its owner has produced no commit, comment, or status change for longer than the stall window, typically three cycles. Return it to open with a note naming what was found so far, so the next owner does not restart from zero.
11. Review before merge. A reviewer who did not write the change checks it against the item's statement of done and the test run, then a human merges. Unreviewed branches stay unmerged, however many there are.

Failure plan

Rehearse these before an unattended run, because each one silently wastes a whole night.

• Two agents change the same file. Expected under parallel work. The merge conflict is caught at review, the second item returns to open with the first change as context. If it happens repeatedly, the items overlap and the queue needs resplitting.
• Disk fills mid-build. The cycle's headroom check stops admitting work, the cleaner prunes artifacts and finished worktrees, and builds resume. If pruning does not recover headroom, stop the swarm rather than corrupting caches.
• An item ping-pongs between owners. Three release events on one item means the item is wrong, not the agents. Convert it into an investigation item for one agent.
• The swarm is busy but not progressing. Sample five merged commits. If they are reformatting, dead scaffolding, or tests asserting nothing, cut the agent count and tighten the statements of done before resuming.
• A requested model or tool is unavailable. Do not silently substitute it. Pause that worker, record the missing capability, and get approval for the replacement.
• You need to stop everything. Know the single command that halts all agents, where every branch and worktree lives, and that nothing merges without a human. Test the stop once while you are watching.

Done

• A roster record names every worker, runtime, model, reasoning setting, checkout, and role
• A queue snapshot from the start and the end of the run shows which items moved, who owned them, and what evidence closed them
• A supervision log records every cycle: idle agents restarted, stalled claims released, disk reclaimed, and the queue counts at that moment
• A merge record shows each merged change reviewed by an agent or person who did not write it, with a passing build and test run against current main
• Disk headroom stayed above the threshold for the whole run, checked from the cycle records
• The stopping condition is written down with its numbers: queue empty, or the round hit saturation at a stated defects-per-effort ratio
• No unreviewed branch was merged and no agent held a claim it was not working

Then use debug-a-production-incident if a merged swarm change breaks something live, and design-a-production-system when the queue keeps producing architecture questions rather than tasks.