Parallel Worktrees & Monorepos

Twelve agents editing one repo at once, none of them stepping on another — because each lives in its own checkout and can only touch the files you let it see.

Why this, for you: you tried running parallel agents on one repo and they collided — one agent's edit landed on another's checkout, or a payments refactor quietly touched the ML service three directories over. The fix isn't discipline. It's physical isolation: a separate working tree per agent, and a filesystem that simply doesn't contain the files an agent has no business editing.

Two settings do the heavy lifting here. Worktrees give each agent its own checkout so parallel edits can't collide on disk. Sparse paths shrink that checkout to one subtree so an agent can't wander across a monorepo. Together they let you fan out wide and sleep at night.

1 Worktrees: one repo, many isolated checkouts

A git worktree is a second working directory backed by the same object database. Each worktree keeps its own HEAD, branch, index, and checkout, so parallel edits cannot collide on disk — yet every commit stays visible from the main repository's history. That's the property that makes parallel agents safe.

Claude Code surfaces this two ways. The --worktree (-w) flag creates an isolated worktree under <repo>/.claude/worktrees/<name> on a new branch worktree-<name> (branching from origin/HEAD) and starts Claude in it — for manual parallel sessions. Mid-conversation, an agent uses the EnterWorktree / ExitWorktree tools to step into a fresh worktree, do bounded work, and step back out.

Worktrees share one object database but keep independent index and working-tree state. Two agents editing the same repo in different worktrees physically cannot overwrite each other's files — and all their commits remain reachable from main.

Exit is not always automatic

ExitWorktree auto-cleans the worktree and its branch only when no changes exist. If there are commits or uncommitted edits, Claude Code prompts you to keep or remove — so an abandoned experiment leaves a branch behind until you decide. The WorktreeCreate / WorktreeRemove hooks can even replace the default git logic for non-git VCS (Perforce, Mercurial).

2 /batch: fan out automatically, one PR per unit

Doing this by hand across a dozen modules is tedious. The bundled /batch skill automates the whole shape: it researches the codebase, decomposes the work into 5 to 30 independent units, presents a plan for approval, then spawns one background agent per unit — each in its own worktree. Every agent implements its slice, runs tests, and opens a pull request. Use /tasks (alias /bashes) to watch them while you keep working in the foreground.

# Decompose a monorepo-wide migration into parallel worktree agents claude /batch "Update all type hints in src/ from typing.Optional, typing.List, etc. to PEP 604 and built-in generics" # → researches, finds 12 modules, presents a plan, then spawns # → 12 agents — each in its own worktree, its own branch, its own PR

Parallel decomposition is not free

Fan out only when the units are truly independent. If slices touch shared files, the agents race on merge. Twelve small PRs also burn more human review attention than one — and practitioners report a wall around ~8 concurrent agents, with quota burn scaling linearly with fan-out. For a tightly-coupled refactor, a single agent with --worktree keeps the isolation without the decomposition cost.

3 Sparse paths: shrink what an agent can even see

Worktrees solve collisions. They don't solve scope — each agent still gets a full repo checkout. In a big monorepo, an agent assigned to payments still sees ML infra, frontend assets, and shared tooling in every glob and file listing. It can't use that noise, and it might change those files by accident.

The worktree.sparsePaths setting (added in v2.1.76) fixes that. When claude --worktree creates a worktree, Claude Code runs git sparse-checkout set --cone with your listed directories. Files outside them are never written to disk:

// .claude/settings.json — committed, shared with the team { "worktree": { "sparsePaths": ["packages/payments", "shared/types", "shared/db"], "symlinkDirectories": ["node_modules"] } }

Behavior	Without sparsePaths	With sparsePaths
File listings / glob	Entire repo	Listed directories only
Read outside cone	Returns the file	File not on disk
Write outside cone	Succeeds	Write fails — no file
Startup time	Full checkout	Only listed paths

The filesystem enforces the scope constraint, not the agent. An agent cannot widen its own view — it would need a new worktree with updated sparsePaths. That intentional friction is what keeps blast radius small. The companion symlinkDirectories avoids duplicating heavy dirs like node_modules into every worktree.

Use it when tasks stay inside a known service and the repo is large enough to be noisy. Skip it when the task crosses service boundaries — an API-contract change or cross-service refactor — because the narrow cone blocks the reads it needs. For varied task domains, keep sparsePaths in personal settings rather than committing it, so it doesn't apply to every worktree regardless of the job.

↪ Your win: fan out wide without collisions

Worktrees isolate on disk — shared object DB, independent checkout; parallel edits can't collide.
/batch decomposes into 5–30 units — one background worktree agent and one PR each, watched via /tasks.
Fan out only when units are independent — coupled slices race on merge; expect a ~8-agent ceiling.
worktree.sparsePaths scopes the checkout — files outside the cone aren't on disk, so writes there fail.
The OS enforces scope, not the agent — pair with symlinkDirectories for heavy shared dirs.

Retrieval practice — recall, don't peek

Question 1What lets two worktrees edit the same repo without colliding on disk?

Question 2The /batch skill decomposes a large change into…

Question 3With worktree.sparsePaths set, a write outside the cone…

Question 4When should you NOT fan out into many parallel worktree agents?

Question 5 · spaced recall from an earlier lessonYou delegate bounded work to a sub-agent mainly to…

Ask me anything. Want a sparsePaths cone for your own monorepo, or help deciding between /batch fan-out and a single --worktree session for a coupled refactor? Next in Part 4: Scheduling & Cloud Routines — moving recurring work off your machine entirely.

✎ Feedback