Sandboxes for Swarms

Two agents writing to the same working directory is a recipe for lost writes and stale views. Git worktrees fix that cleanly — until agent count climbs high enough that the branching itself becomes the bottleneck.

Why this, for you: parallel agents need filesystem isolation or they corrupt each other's work. This lesson is the default mechanism (worktrees), its limits, and the contrarian alternative for true swarms — so you pick by agent count and coordination infrastructure, not by reflex.

A git worktree is an isolated repo copy on its own branch that shares git objects with the main checkout — so creation is fast and disk overhead is minimal. Each agent gets a private sandbox: wrong output, delete the worktree; correct output, submit the branch for merge.

1 Worktrees: one agent, one branch, one PR

The isolation guarantee is structural: no shared working directory, no interference with main during execution, failures contained to one worktree, each agent's changes captured on a separate branch. The batch pattern is N agents → N worktrees → N PRs, each validated independently by CI.

# fan three tasks into isolated worktrees git worktree add ../wt-rename -b agent/rename git worktree add ../wt-audit -b agent/audit-log git worktree add ../wt-docs -b agent/api-docs # bad output? git worktree remove. good output? push the branch.

Worktrees isolate files, not runtime

The biggest trap: worktrees separate files and branches but not ports, databases, caches, secrets, or background processes. Two agents each running a dev server on port 3000, or sharing one Postgres, collide even with independent checkouts. Other limits: per-worktree setup (npm install, Docker builds) re-runs each time; fifty worktrees on a monorepo saturate disk; stateless read-only agents need no isolation at all.

2 At 10+ agents, branching becomes the cost

The branch-per-feature model assumes a few long-lived branches with human reviewers. As agent count rises past ~10 making frequent small commits, three failure modes compound: merge conflicts grow with concurrent branches, rebasing burns agent context that should go to implementation, and logical conflicts (a signature change + a new callsite) merge cleanly but fail to compile.

The single-branch counterpoint: all agents commit directly to main, with three mechanical substitutes for branch isolation — advisory file reservations with TTL (a crashed agent's lock expires, degrading gracefully), a pre-commit guard that rejects commits to another agent's reserved files, and a Destructive Command Guard blocking git reset --hard, push --force, rm -rf at the shell.

Single-branch is the contrarian position — and conditional

Claude Code's documented recommendation is worktrees; single-branch (the Agent Flywheel position) is strictly riskier without its preconditions: coordination infrastructure (Agent Mail or equivalent), an installed DCG, fungible agents (a specialist writing a signature another immediately builds on becomes a single point of failure), and pre-partitioned small tasks. Under ~10 agents or with variable task overlap, worktrees are the lower-risk default. Worktree guides cap their own recommendation at 3–5 parallel agents.

↪ Your win: isolation matched to scale

Default to worktrees — one agent, one branch, one PR; delete on failure, merge on success.
Isolate runtime separately — worktrees don't touch ports, DBs, caches, or processes.
Watch the disk and setup cost — each worktree re-runs install and duplicates tracked files.
Switch to single-branch only past ~10 agents — and only with the four preconditions.
Enforce mechanically, not by instruction — a Destructive Command Guard, not a "please don't."

Retrieval practice — recall, don't peek

Question 1A git worktree gives each agent…

Question 2Worktrees notably do NOT isolate…

Question 3Past ~10 parallel agents, rebasing branches is costly because it…

Question 4The Destructive Command Guard exists because…

Question 5 · spaced recall from Lesson 4The factory model replaces real-time human attention with…

Ask me anything. Want the lazy-worktree variant (relocate on first write, not on dispatch), or how advisory reservations with TTL beat hard locks when an agent crashes? Next in Part 2: Agents in the Pipeline — running them headless in CI.