The Swarm: Parallel Coding Agents in Git Worktrees

A single coding agent handles a repo's tasks one at a time even when those tasks are independent. The session's promise is to run many agents on one repository without collisions by giving each its own isolated space via git worktrees. The plan is to deliberately fan work out to a fleet and then reassemble it on purpose rather than hope git sorts it out.

A lone coding agent processes a backlog one task at a time, which feels slow — but the delay isn't the model's speed. It's that a single agent is a queue with exactly one server. When four independent tasks wait behind one, none of them actually depend on the others; they're stuck only because of an accidental scheduling choice: one agent, one working tree, one thing at a time.

The obvious first attempt — many agents in the same directory — works briefly and then breaks. The danger is that it fails as damaged work, not as a clean error: overwritten files, mixed-up staging, shifting HEADs, and lockfile collisions. A single working tree is one shared mutable surface, and parallel edits on shared state are a race you can't win by adding more runners. What's missing is isolation, a primitive git already provides.

One orchestrator owns the split and never writes code. It has exactly three jobs — split the backlog into non-overlapping slices, dispatch one agent per isolated slice, and merge the finished branches. Each is a judgement only the conductor can make because a worker can't see the other workers. The conductor's only products are the plan and the merge; the moment it starts editing code, it becomes a fourth worker with a global view — the one role that can't be isolated.

Branching isn't the primitive you need — it gives many histories but only one working tree, so agents still serialize on switching files in place. Two agents can't be on two branches at once. Git worktrees instead give many branches with many working trees: each agent gets its own directory, index, and HEAD, all backed by the same shared object store. The result is N desks on one clone's worth of objects, a trick git has shipped since version 2.5.

A worktree isolates four things — working tree, index, HEAD, and checked-out branch — but silently shares everything else, including .git/config, refs, and hooks. When three agents each set their identity the obvious way, they race on the shared config file: two commands fail to lock it, yet all three commit anyway. Commit messages look right, but the author field is wrong on every commit — the one field you'd use to audit who did what. A worker may write its own tree but must never write the shared config.

The entire setup half of the pattern is four commands: three `git worktree add` calls creating a branch each, plus `git worktree list` to verify. Every `../sw/NN` is a full checkout an agent can build in without touching the others. Crucially, there's no re-clone and no second copy of history — the object store is shared, so the marginal cost of another agent is just its working files. Fan-out is genuinely cheap.

A real run on a scratch repo split into three independent tasks, ran three agents concurrently in three worktrees, and merged them back. The before-and-after git graphs show three features advanced in the wall-clock time one agent needs for one. The fan-out cost only four commands — the real work was the fan-in, the serial merges and conflict triage that the later slides cover in depth.

To keep the swarm cheap, people link a shared `.venv` or `node_modules` into each worktree. That same trick arms a data-loss trap: if a worktree carries a junction pointing outside itself, removing the worktree follows the link outward and deletes the target's contents — then exits 0 with no output at all. `rm -rf` and `shutil.rmtree` behave identically. This actually fired in the team's own fleet nine hours before doors.

The deck was planned in June but the lab was run today, before it was written. The plan mostly survived; where it didn't, the slides changed rather than the run. Three edits resulted — a whole slide added, an agent-identity fix, and a teardown unlink step. Every VCN lab gets run before it's taught because it's the cheapest quality gate available: tonight it cost about twenty minutes and caught two silently-passing failures that would otherwise have reached fifty laptops.

The first lab step is to open your own repo and name three tasks that touch disjoint sets of files. Independence is the whole game, and this is the only step where you actively choose it. The setup is three `git worktree add` commands plus a list, with cross-platform variants shown. The hard gate: you want four rows and three distinct branch names, and if two tasks want the same file they are really one task — merge them now, before any agent touches anything.

Each worktree gets one terminal and one agent, driven by z.ai plus Claude Code and fueled by Nebius credits. The identity is set through `GIT_AUTHOR`/`GIT_COMMITTER` environment variables per process — never `git config`, which writes the shared file and races (the slide 6 bug). The brief follows three rules: tight named scope, stay in your own tree with no cross-task reads, and commit only when tests are green. Isolation is enforced by the filesystem, not by trusting the agent to behave.

While the workers run, the conductor acts as a scheduler — checking who's alive, who has committed, and who is stuck — using `git worktree list` and a loop over each tree's last commit as a status board. The temptation to open an editor must be resisted: the moment you edit, you become a fourth worker with a global view. The checkpoint verifies each tree's commit is authored by its own agent; if two rows share an author, the slide 6 bug is present and must be fixed before merging, since attribution becomes permanent afterward.

Fan-out is parallel but fan-in must be serial. The temptation is to merge everything at once and let git sort it out — don't. Merging one branch at a time means any conflict is traceable to exactly which branch introduced it. Using `--no-ff` keeps a merge commit per agent so the graph still shows who did what after the fan-in, which a fast-forward would erase. Two clean merges and one conflict is a normal, healthy result; a swarm that never conflicts probably had tasks too small to be worth splitting.

When two agents edited a file nobody expected to be shared, neither is wrong — the merge isn't a contest, both features should survive, so keep both. When it's harder, hand the conflict to a fresh agent with both intents. But the truly dangerous case is the semantic conflict: both branches merge cleanly with no markers, yet the result is broken — one agent renamed a field, another wrote a caller for the old name elsewhere. Measured at 5–10% of parallel-agent runs, git will never flag it, so run the tests after the last merge.

Teardown order is safety-critical. If you linked anything into a worktree to make it cheap, you must drop that link first — `rmdir` removes only the link, while `rm -rf` follows it and deletes the target. Only then remove the worktree, prune stale metadata, and delete the branch. Skipping the unlink reproduces the slide 9 data-loss that exits 0 silently. Keep `-d` rather than `-D`, because its refusal to delete unmerged branches is the only thing protecting an agent's unfinished work.

Fanning out isn't always a win: CodeCRDT's 600 trials measured up to 21% speedup on some task shapes and up to 39% slowdown on others. The one-sentence test is to parallelize only work that shares no write surface — if two tasks edit the same file they are one task, and splitting them turns a five-minute edit into a merge you reason about twice. Two human trust gates bracket the run: Gate 1 reviews the conductor's split before fan-out, and Gate 2 reviews the merged result before it ships. Agents commit; humans integrate.

The session's four deliverables: a conductor that fans N agents across N worktrees on one repo; per-worktree isolation plus a clear map of the four things worktrees do not isolate; a fan-in playbook covering serial merges, conflict-by-intent resolution, and a teardown that unlinks before removing; and the one-sentence test for whether work should be fanned out at all. Together they turn a single-agent workflow into a disciplined fleet.