Swarms in Worktrees: How Claude Code Agents Work in Parallel

Parallel coding agents sharing one checkout overwrite each other’s edits. Git worktrees give agents separate working directories over shared history, eliminating file-level collisions.

1 Shared-checkout failure mode

Two agents editing the same files produce a chimera diff: partial refactors, broken imports, merged incompatible changes. No error is raised; the last write wins silently.

Cause: read-think-write is not atomic, and agents have no shared awareness of concurrent editors.

One directory, three writers. The last write wins and the others vanish.

2 Worktrees

A git repository has an object database (.git) and a working directory (editable files). Default layout: one working directory per repository.

git worktree add attaches multiple working directories to one object database:

Each directory can have a different branch checked out.
Commits from any worktree land in the shared object store.
Not a clone — no duplicated history, no remote sync between copies.
Editing a file in one worktree does not affect the same path in another.

3 Claude Code isolation

Claude Code sets up worktree isolation automatically. Manual option:

claude --worktree   # or: claude -w

Isolation levels:

--worktree flag — creates a fresh worktree; leaves your checkout and branch untouched.
Agent view — one worktree per dispatched session automatically.
Subagents with isolation: "worktree" — helper agent gets its own directory; removed if unchanged.
/batch — splits one task into subagents, isolated in their own worktrees, each opening a PR:

/batch add structured logging to every handler in src/api

Fan-out requires enumerable units of work in the prompt:

Try three different fixes for the flaky test in tests/pool_test.go — one per
worktree, each on its own branch. Tell me which one holds. Don't
merge anything yet.

In parallel, each in its own worktree: add rate limiting to /upload, backfill
the types in lib/analytics, and upgrade the test runner to vitest 3. Open a
separate PR for each.

Port the four adapters in src/adapters to the new client interface. One
subagent per adapter, isolated, and stop each one as soon as its adapter's
tests pass.

Requirements for useful fan-out: separable units, explicit parallel request, stopping condition per unit. Vague prompts (“clean up the codebase”) do not decompose.

4 Parallel hypothesis testing

Example: intermittent test failure with three theories (race, fixture teardown, timeout).

Dispatch three subagents, one theory each, each in its own worktree on its own branch.
All edit the same files concurrently without collision.
Compare three branches and diffs; merge the winner; discard other worktrees.

Three lanes, three branches, no contention — then one merges and the rest are dropped.

5 When to isolate

Use worktree isolation when:

Agents will touch overlapping files
Several independent tasks run concurrently
A large change decomposes cleanly
Competing approaches should be compared in parallel

Skip when:

Single agent (nothing to collide with)
Small, quick edits (setup cost exceeds work)
Heavy per-directory dependency installs (node_modules, virtualenv per worktree)

6 Limits

Worktrees isolate files inside the git tree only. Shared state outside remains a collision surface:

One development database across agents (migration conflicts)
Stateful MCP (Model Context Protocol) server sessions shared between agents
Checklist files outside worktrees
Shared Redis or other external state

Cost is unchanged: three agents on one bug is three times the tokens. Scoping — narrow tasks with clear stop conditions — controls spend; isolation controls safety.

Agents. Collide. Silently. Worktrees. Separate. Files. Not. Databases. Scope. Narrowly.