Why it matters
Two agents editing one checkout overwrite each other's files, share a build cache and race on the same test database. Switching branches with git checkout changes global state, so it cannot isolate concurrent tasks. Worktrees solve the filesystem part cheaply by sharing the object store while giving each task a separate working directory, which is why they became the default isolation primitive for parallel coding agents.
Mental model
It is separate desks in one office sharing a filing cabinet. The metaphor breaks because the cabinet is shared, so a branch rename at one desk moves the refs under everyone, and two agents can still collide while sitting at different desks.
How it works
- 1Create one worktree per task from an explicit base commit under a path keyed by task id.
- 2Give each worktree its own branch name rather than reusing a shared one.
- 3Install dependencies and build caches per worktree, or point them at a task-scoped cache directory.
- 4Pin a test database or port per worktree so concurrent runs cannot collide.
- 5Remove the worktree and its branch when the task closes, then prune stale administrative files.
- 6Record the worktree path and base SHA in run metadata so any patch can be reproduced.
Step 1 of 6
Create one worktree per task from an explicit base commit under a path keyed by task id.
Figure. The mechanism in this page's own steps. The figure adds sequence, not new claims.
What to notice. A step can be read alone, but the order is the mechanism. The control lets you stop on any one.
Text version
The page's steps: 1. Create one worktree per task from an explicit base commit under a path keyed by task id. 2. Give each worktree its own branch name rather than reusing a shared one. 3. Install dependencies and build caches per worktree, or point them at a task-scoped cache … 4. Pin a test database or port per worktree so concurrent runs cannot collide. 5. Remove the worktree and its branch when the task closes, then prune stale administrative … 6. Record the worktree path and base SHA in run metadata so any patch can be reproduced.
- Create one worktree per task from an explicit base commit under a path keyed by task id.
- Give each worktree its own branch name rather than reusing a shared one.
- Install dependencies and build caches per worktree, or point them at a task-scoped cache directory.
- Pin a test database or port per worktree so concurrent runs cannot collide.
- Remove the worktree and its branch when the task closes, then prune stale administrative files.
- Record the worktree path and base SHA in run metadata so any patch can be reproduced.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Worktree per task | Cheap isolation, shared objects | Disk per checkout, shared refs | Tasks share branches or need separate clones |
| Full clone per task | Complete isolation | Slow setup, duplicated objects | Repository is large and tasks are short |
| One checkout, sequential tasks | Simplest | No parallelism, state leaks | More than one agent runs at once |
| Container with a mounted worktree | Isolation plus reproducibility | Image and mount complexity | Team lacks container tooling |
Good for
Cheap isolation, shared objects
Cost
Disk per checkout, shared refs
Fails when
Tasks share branches or need separate clones
- Tasks share branches or need separate clones
- Repository is large and tasks are short
- More than one agent runs at once
- Team lacks container tooling
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: Worktree per task is good for Cheap isolation, shared objects, costs Disk per checkout, shared refs, and fails when Tasks share branches or need separate clones. Full clone per task is good for Complete isolation, costs Slow setup, duplicated objects, and fails when Repository is large and tasks are short. One checkout, sequential tasks is good for Simplest, costs No parallelism, state leaks, and fails when More than one agent runs at once. Container with a mounted worktree is good for Isolation plus reproducibility, costs Image and mount complexity, and fails when Team lacks container tooling
Failure modes
- Shared branch collision. Two agents commit to the same branch and one rebases over the other. Debug: list the branch attached to each worktree and assert they are distinct.
- Cache collision. Concurrent builds write the same cache directory and produce corrupt artefacts. Debug: print cache paths per run and check for overlap.
- Stale worktree. A closed task leaves a locked worktree that blocks prune. Debug: list worktrees, then remove entries whose directory no longer exists.
In production
Track worktrees per host against disk and memory. Reap idle worktrees on a timer and alert on lock files older than a day.
Common misconceptions
People think: Worktrees are the same as branches.
Actually: A branch is a ref and a worktree is a checkout; many worktrees can point at one branch and still collide.
People think: Cloning is the only safe isolation.
Actually: Worktrees isolate the working tree cheaply, while clones add isolation of refs and config at a setup cost.
Interview angle
Distinguish filesystem isolation from ref isolation and say which the task needs. A strong answer covers per-task caches, ports and cleanup, and notes that two worktrees on one branch still collide. Treating a worktree as a branch, with no mention of shared refs, misses the failure that bites parallel agents.
Sources
- Git, git-worktree documentation — multiple working trees attached to one repository.
- Git, gitworkflows — branch and integration conventions.
- Anthropic, Effective harnesses for long-running agents — isolated workspaces for long agent sessions.