Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Worktree Isolation

Pattern

A reusable solution you can apply to your work.

Understand This First

  • Subagent – each subagent typically gets its own worktree.

Context

At the agentic level, worktree isolation is the practice of giving each agent its own separate checkout of the codebase. When multiple agents work on the same project simultaneously, or when an agent works alongside a human, each operates in its own Git worktree or branch, preventing their changes from colliding.

This pattern applies the well-established principle of isolation from version control and concurrent programming to agentic workflows. Just as two developers working on the same file at the same time create merge conflicts, two agents editing the same codebase create the same problem, but faster and with less ability to resolve conflicts on their own.

Problem

How do you prevent multiple agents, or an agent and a human, from stepping on each other’s changes when working on the same codebase?

When two agents edit the same file simultaneously, the results are unpredictable. One agent’s changes may overwrite the other’s. An agent may read a file that’s in the middle of being modified by another agent, getting a half-written state. These problems are invisible until something breaks, and debugging concurrent agent conflicts is difficult because neither agent is aware the other exists.

Forces

  • Parallelism is valuable. Running multiple agents on different tasks multiplies throughput.
  • Shared state (the filesystem, the Git index) creates collision risks when accessed concurrently.
  • Agents are unaware of each other. Unlike human developers who can coordinate verbally, agents don’t know other agents are working.
  • Merge complexity increases with the size and overlap of concurrent changes.

Solution

Give each concurrent agent its own Git worktree: a separate checkout of the repository that shares the same Git history but has its own working directory, branch, and index. Each agent works in isolation, and changes are integrated through the normal Git merge process after each agent’s work is reviewed.

The setup is straightforward:

git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b

Each worktree is a full working copy. An agent running in project-feature-a can read, write, and test without affecting project-feature-b. When both agents finish, their branches are merged through pull requests, with any conflicts resolved by a human or a dedicated merge agent.

Worktree isolation also applies to the human-agent relationship. If you want to continue working on the codebase while an agent handles a separate task, put the agent in its own worktree. This prevents the disorienting experience of files changing under your feet while you’re reading them.

Tip

When running parallel agents with parallelization, always use worktree isolation. The time spent setting up worktrees is negligible compared to the time lost debugging concurrent file conflicts.

How It Plays Out

A developer assigns three agents to work in parallel: one adding a new API endpoint, one refactoring the database layer, and one writing integration tests. Each agent gets its own worktree on its own branch. All three work simultaneously without interference. When they finish, the developer reviews three pull requests and merges them in sequence, resolving a minor conflict where the API endpoint and the database refactoring both touched a shared configuration file.

Without worktree isolation, the same scenario would have been chaotic: agents overwriting each other’s changes, tests failing because of half-applied modifications, and the developer spending more time untangling conflicts than the agents saved.

Example Prompt

“Create a new git worktree on a branch called feat/search-api. Work entirely in that worktree. When you’re done, I’ll review the branch and merge it into main.”

Consequences

Worktree isolation makes parallel agent work safe and predictable. It eliminates an entire class of concurrency bugs (file-level conflicts) and lets you scale to multiple agents with confidence. It also creates clean, reviewable pull requests: each worktree’s branch represents a single, coherent set of changes.

The cost is disk space (each worktree is a full working copy) and merge effort (changes must be integrated afterward). For most projects, the disk cost is negligible. The merge cost is real but manageable, especially when agents work on well-separated parts of the codebase, which they should, if the tasks were decomposed well.

  • Enables: Parallelization — worktree isolation is a prerequisite for safe parallelization.
  • Depends on: Subagent — each subagent typically gets its own worktree.
  • Uses: Version Control — worktrees are a Git feature that extends version control to concurrent agents.
  • Uses: Approval Policy — changes from isolated worktrees go through the normal review and approval process.