How to Orchestrate a Multi-Agent Swarm

Nothing about a swarm requires the agents to talk to each other, and nothing requires them to be autonomous. A swarm is a set of agent processes with a shared objective and a shared repository. The coordination problem is the same one two human developers have when they touch the same file at the same time, except the agents work faster, do not read Slack, and will happily overwrite each other without noticing.

So the substrate matters more than the prompt. You need a way to divide responsibility, a way to reserve files, a way to pass messages, and a gate before anything lands on the main branch. Everything below is about that substrate.

Most swarms converge on three roles. An architect decides what gets built and splits the work. Workers do the building, each inside its own slice of the codebase. A reviewer reads the diffs and decides what merges. The reason three works is that it separates the three jobs that go wrong when one agent does everything: planning drift, unbounded edits, and self-approval.

In Workspace the roles are exactly `architect`, `worker`, and `reviewer`. A role is bound to a pane, not to a prompt, and the binding lives in the local daemon rather than in the agent's context. That distinction is doing real work: a request to approve a branch carries only the pane it came from, and the daemon looks that pane's role up itself, so no agent can assert a role inside the request that asks to merge.

$ mogging role 1 architect
$ mogging role 2 worker
$ mogging role 3 worker
$ mogging role 4 reviewer

A practical starting shape is one architect, two workers, and one reviewer. Add workers as the work parallelizes, not before. Two workers on genuinely independent slices beat six workers queuing on the same three files, and you can watch the difference happen live if your terminal is streaming rather than polling.

The failure that ruins swarms is two agents editing one file. It does not announce itself. Both agents report success, both diffs look reasonable in isolation, and the second write silently erases the first. No amount of prompting fixes this, because the agents have no shared view of what the others are touching.

The fix is a claim ledger: before an agent edits, it reserves a path pattern; when it is done, it releases. Any other agent asking for an overlapping pattern is refused. The ledger has to live outside the agents, in a process that all of them talk to, or it is not a ledger. Be clear about what it does: a ledger advises, it does not intercept file writes. It refuses the reservation, loudly, and the merge gate is what catches a stray edit that ignored it.

# run by the agent, inside its own pane
$ mogging claim "src/api/**"
$ mogging owners
#7 pane 2:worker owns src/api/**
#8 pane 3:worker owns src/ui/**
$ mogging release "src/api/**"

Note who runs those commands. A claim is made by the agent, from inside its own pane, because the pane is the identity the ledger trusts. Claims are also coarse on purpose: patterns like `src/api/**` are easier for an architect to hand out than individual files, and they fail loudly at reservation time instead of quietly at merge time.

Agents need to tell each other things: the schema changed, the endpoint moved, this test is now the contract. The tempting design is one giant shared context that every agent reads. It does not scale, because every message costs every agent tokens, and the important message is buried among the routine ones.

A mailbox scales instead. Messages are addressed and read on demand. A worker that finishes a migration sends one note to the reviewer; the other worker never pays for it.

$ mogging mail send --to 4 "users table migrated, review branch feat/users"
$ mogging mail read

The last gate is the one that matters. An agent that can merge its own work can also merge its own mistake, and the whole point of the reviewer role is that some other process reads the diff first.

Workspace records an approval against a branch from the pane bound to the reviewer role, and the daemon resolves that role itself rather than trusting anything in the request. The approval verb is also deliberately absent from the tool surface the app exposes to agents over MCP, so an agent driving the app through tools cannot approve anything. If you take one idea from this guide into your own setup, take that one: keep the merge gate off the tool surface you hand the agent.

# only a pane whose daemon-side role is reviewer may approve
$ mogging approve feat/users
$ mogging approvals

Claims stop two agents from reserving the same files. Worktrees stop them from sharing a working directory at all. Each agent gets its own git worktree on its own branch, so a build in one does not disturb a test run in another, and a bad edit is contained to one branch.

Workspace creates a worktree per agent and shows a redacted diff before anything merges, with the merge itself guarded behind the reviewer approval above. Secrets are stripped from the diff before it leaves the module that produced it, which matters when the thing reading your diff is a language model.

It does not mean an autonomous manager agent that runs the show. In Workspace there is no orchestrator process deciding what happens next. A person or a script drives the loop, using the same control verbs shown above. The roles, the ledger, the mailbox, and the gate are coordination primitives, and the intelligence stays where you can see it.

The payoff is that every step of the swarm is a command you can read, replay, and put in a script. When something goes wrong, you debug a shell history.

Four agents means four times the token spend, and providers meter in session and weekly windows. A swarm is the fastest way to discover where your limits actually sit. Before you scale one up, read the guide on usage limits and profile failover, which covers what happens when a worker hits a wall halfway through a migration.

The full command reference for roles, claims, mail, and approvals lives in the swarm coordination docs. To see the whole category this fits into, start at the AI agent command center.