Skip to content
AI Engineer Guide.

concept · coding · intermediate · concept 17 of 30

Worktrees

0 of 30 complete

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

Mechanism, step by stepInteractive
  1. 1Create one worktree per task from an explicit base commit under a path keyed by task id.
  2. 2Give each worktree its own branch name rather than reusing a shared one.
  3. 3Install dependencies and build caches per worktree, or point them at a task-scoped cache directory.
  4. 4Pin a test database or port per worktree so concurrent runs cannot collide.
  5. 5Remove the worktree and its branch when the task closes, then prune stale administrative files.
  6. 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.

Step 1/6 · step 1

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.

  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 directory.
  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 files.
  6. Record the worktree path and base SHA in run metadata so any patch can be reproduced.

Trade-offs

ChoiceGood forCostFails when
Worktree per taskCheap isolation, shared objectsDisk per checkout, shared refsTasks share branches or need separate clones
Full clone per taskComplete isolationSlow setup, duplicated objectsRepository is large and tasks are short
One checkout, sequential tasksSimplestNo parallelism, state leaksMore than one agent runs at once
Container with a mounted worktreeIsolation plus reproducibilityImage and mount complexityTeam lacks container tooling
Trade-off mapInteractive

Good for

Cheap isolation, shared objects

Cost

Disk per checkout, shared refs

Fails when

Tasks share branches or need separate clones

  1. Tasks share branches or need separate clones
  2. Repository is large and tasks are short
  3. More than one agent runs at once
  4. 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