One agent is a tool. A swarm is a team.
The moment I stopped asking a single agent to “do everything” and started splitting work across several, the quality jumped. Each agent gets a narrow, well-scoped job — refactor this module, write tests for that API, run the migration audit — instead of one agent trying to hold the whole codebase in context.
How the swarm is shaped
- Coordinator: a lean agent that reads the repo, cuts the work into units, and files them. It decides what runs in parallel.
- Workers: disposable agents, each owning a slice — a directory, a module, a test file. They never touch shared state.
- A human diff gate: the only thing that must not be parallelized is the merge.
# one worker per slice, fully observable
tmux new-session -d -s worker-1 'pi -p "refactor src/auth into small modules"'
tmux new-session -d -s worker-2 'pi -p "add unit tests for src/payments"'This is exactly the pattern Pi pushes you toward — no built-in sub-agents, so you orchestrate with tmux or your own extension. Full visibility, direct interaction, no hidden parallel processes.
Where swarms break
Parallel agents fail the same way parallel humans do: conflicting writes, duplicated work, and one worker blocking on another’s output. The fix is to make the units write-isolated — separate files, separate branches, and a coordinator that only hands out work with a clear file boundary.
{ "tasks": [
{ "id": "1", "scope": "src/auth/*", "branch": "swarm/auth" },
{ "id": "2", "scope": "src/payments/*", "branch": "swarm/payments" }
]}A swarm turns a weekend’s worth of mechanical work into an afternoon. It turns nothing into a merge conflict if you skip the partition step. Keep the units small, keep the writes isolated, and stay the gate.