explained comic · 19 pages · your annotated copy
an educational manga explainer
The Swarm: Parallel Coding Agents in Git Worktrees
comicexplain
session notes
kept private to your copy — sign in to add notes.
my take on page 1
key idea
Isolation, not more agents, is what makes parallel coding agents safe.
flip ↺
why this matters
Without isolation, parallel agents corrupt each other's work in ways that pass silently and reach production.
flip ↺
p. 1 · 19
my take on page 2
key idea
One agent is slow because it is a single-server queue, not a slow model.
flip ↺
why this matters
Recognizing the real bottleneck tells you to change scheduling, not chase a faster model.
flip ↺
p. 2 · 19
my take on page 3
key idea
One working tree is one shared mutable surface, and parallel edits race.
flip ↺
why this matters
The failure arrives as corrupted work, not an error, so you must prevent it structurally.
flip ↺
p. 3 · 19
my take on page 4
key idea
The conductor's only products are the plan and the merge.
flip ↺
why this matters
Keeping the orchestrator out of the code preserves the one global-view role that cannot be isolated.
flip ↺
p. 4 · 19
my take on page 5
key idea
Worktrees give N working directories backed by one shared object store.
flip ↺
why this matters
You get real parallelism cheaply, without re-cloning history for each agent.
flip ↺
p. 5 · 19
my take on page 6
key idea
Shared config races silently corrupt the commit author field.
flip ↺
why this matters
Wrong authorship destroys your only record of which agent did what, and it fails without an error.
flip ↺
p. 6 · 19
my take on page 7
key idea
Four commands stand up N isolated arenas cheaply.
flip ↺
why this matters
Cheap isolation is what makes fanning work out across many agents practical.
flip ↺
p. 7 · 19
my take on page 8
key idea
Fan-out is cheap; fan-in is where the real work lives.
flip ↺
why this matters
Budget your effort for merging, because that is where the swarm's cost concentrates.
flip ↺
p. 8 · 19
my take on page 9
key idea
Removing a worktree can follow a link outward and delete real data.
flip ↺
why this matters
The cheap-swarm trick can quietly destroy files that were never in the worktree.
flip ↺
p. 9 · 19
my take on page 10
key idea
Running a plan before teaching it catches failures that pass silently.
flip ↺
why this matters
A short rehearsal prevents silent bugs from reaching every learner's machine.
flip ↺
p. 10 · 19
my take on page 11
key idea
Pick tasks with disjoint files; overlapping ones are really one task.
flip ↺
why this matters
Independence at this step is what determines whether the whole night is cheap or expensive.
flip ↺
p. 11 · 19
my take on page 12
key idea
Set agent identity via env vars per process, never shared config.
flip ↺
why this matters
Per-process identity fixes the silent authorship race and lets you audit each agent's work.
flip ↺
p. 12 · 19
my take on page 13
key idea
Poll the fleet's status but never help by editing code.
flip ↺
why this matters
Editing collapses your global oversight into just another isolated worker's blind spot.
flip ↺
p. 13 · 19
my take on page 14
key idea
Merge serially with --no-ff so each conflict is traceable.
flip ↺
why this matters
Serial fan-in preserves attribution and pins every conflict to a single responsible branch.
flip ↺
p. 14 · 19
my take on page 15
key idea
Keep both intents; catch clean-merging semantic conflicts with tests.
flip ↺
why this matters
Semantic conflicts pass every merge check and only tests after the last merge reveal them.
flip ↺
p. 15 · 19
my take on page 16
key idea
Unlink internal links before removing a worktree, and keep -d.
flip ↺
why this matters
The command order is the only thing between routine cleanup and irreversible data loss.
flip ↺
p. 16 · 19
my take on page 17
key idea
Fan out only work that shares no write surface; humans gate split and merge.
flip ↺
why this matters
Measured trials show fanning out can slow you down 39 percent when tasks overlap.
flip ↺
p. 17 · 19
my take on page 18
key idea
You leave with a conductor, an isolation map, a fan-in playbook, and a test.
flip ↺
why this matters
These four artifacts turn a single-agent queue into a repeatable parallel workflow.
flip ↺
p. 18 · 19
my take on page 19
key idea
Real isolation, disjoint splits, and human-gated fan-in make swarms work.
flip ↺
why this matters
Getting these right converts a slow single-agent queue into safe, auditable parallel progress.
flip ↺
p. 19 · 19
flashcards · all 19
key idea
Isolation, not more agents, is what makes parallel coding agents safe.
click to flip ↺
why this matters
Without isolation, parallel agents corrupt each other's work in ways that pass silently and reach production.
click to flip ↺
card 1 · 19
one card per page — cycle through before you close the book.
index of key ideas
1Isolation, not more agents, is what makes parallel coding agents safe.
2One agent is slow because it is a single-server queue, not a slow model.
3One working tree is one shared mutable surface, and parallel edits race.
4The conductor's only products are the plan and the merge.
5Worktrees give N working directories backed by one shared object store.
6Shared config races silently corrupt the commit author field.
7Four commands stand up N isolated arenas cheaply.
8Fan-out is cheap; fan-in is where the real work lives.
9Removing a worktree can follow a link outward and delete real data.
10Running a plan before teaching it catches failures that pass silently.
11Pick tasks with disjoint files; overlapping ones are really one task.
12Set agent identity via env vars per process, never shared config.
13Poll the fleet's status but never help by editing code.
14Merge serially with --no-ff so each conflict is traceable.
15Keep both intents; catch clean-merging semantic conflicts with tests.
16Unlink internal links before removing a worktree, and keep -d.
17Fan out only work that shares no write surface; humans gate split and merge.
18You leave with a conductor, an isolation map, a fan-in playbook, and a test.
19Real isolation, disjoint splits, and human-gated fan-in make swarms work.
comicexplain
paste a paper, get an annotated comic — pages appear in seconds.
front cover