# One Agent, One Worktree: Isolation and Concurrency for Coding Agents

> 🗓️ **Last updated: September 2026**

Three coding agents start from the same checkout. One upgrades a package. One refactors the service that uses it. One fixes a test by changing the shared fixture. Each finishes successfully in the filesystem it happened to inherit. The combined branch resembles a group project in which nobody was told there were other group members.

Parallel coding is not primarily a coordination problem. It is first an isolation problem.

## The unit of work needs a boundary

Give each agent a dedicated branch and working tree created from a known commit. Record that base commit with the task. The agent may inspect the wider repository, but it should modify only its own checkout. This creates a reviewable patch, prevents uncommitted changes from bleeding between tasks, and makes cleanup unsurprising.

Git worktrees are a practical local mechanism because they allow multiple working trees attached to one repository. Separate clones or ephemeral runners may be more appropriate for remote execution. The mechanism matters less than the invariant: one task owns one isolated filesystem and one branch.

Do not share build outputs between concurrent tasks unless the toolchain explicitly supports it. Generated files, package caches, local databases, ports, and containers can create hidden coupling. A clean source branch is not isolated if every agent points at the same mutable test database.

## Concurrency starts with task topology

Before dispatching work, identify dependencies between tasks. Two independent documentation changes can proceed together. A schema migration and the code consuming that schema have an ordering decision. Two changes to the same central file may be logically independent and mechanically expensive to merge.

A useful dispatcher classifies tasks as independent, ordered, or conflicting. Independent tasks may run concurrently. Ordered tasks wait for a predecessor or branch from its result. Conflicting tasks should be combined or deliberately sequenced.

This is not multi agent choreography. The agents do not need to hold a committee meeting. The delivery system needs to understand the version graph.

## Preserve the handoff artifact

Each task should finish with more than changed files. Require a compact handoff containing the base commit, commits produced, files changed, tests executed, test results, unresolved concerns, and any deviation from the contract. This artifact lets a reviewer understand the work without replaying an entire conversation.

Long running agent research from Anthropic similarly emphasizes incremental progress and structured artifacts that carry state across sessions. Git history already provides part of that structure. Use it. A transcript is useful for diagnosis, but a coherent commit remains the native unit of software review.

## Merge through evidence

An agent branch should pass its scoped verification before entering the merge queue. The target branch must then run the required integration checks because other changes may have landed. Never assume that two green branches produce one green branch. Version control has spent decades offering educational examples to the contrary.

For conflicts, ask for a fresh analysis against the updated target. A textual merge that removes conflict markers may still violate behavior. Rerun tests and review the combined intent. High risk conflicts should return to a human owner.

Keep commits small and meaningful. An agent that mixes a functional change, formatting sweep, package upgrade, and generated file refresh into one commit has created a review hostage situation.

## Control shared resources

Allocate unique database names, container names, ports, and temporary directories per task. Use scoped credentials and disposable environments for untrusted execution. Do not let two agents deploy to the same shared development slot unless testing race conditions is the actual assignment.

Limit concurrency according to the resources that are genuinely scarce: build capacity, external API quotas, integration environments, and reviewer attention. Starting fifty tasks is easy. Reviewing fifty simultaneous architectural decisions is merely a creative way to move the queue.

## Failure modes

The first failure is branch isolation without environment isolation. Tests alter shared state and create results that cannot be reproduced.

The second is stale success. A branch passed tests against an old base and enters the target without current integration checks.

The third is invisible dependency. Two tasks were described as independent but change the same contract. A task topology review would have exposed the relationship before compute and reviewer time were spent.

The fourth is transcript dependence. Nobody can understand the patch without reading the agent's entire session. The code, commits, tests, and handoff should explain the result.

## The architect's checklist

1.  Create one isolated branch and filesystem for every task.
    
2.  Record the exact base commit and execution environment.
    
3.  Classify task dependencies before parallel dispatch.
    
4.  Isolate mutable test resources and deployment targets.
    
5.  Require scoped tests before queueing and integration tests after merging.
    
6.  Preserve a structured handoff beside the commits.
    

Parallel agents can increase throughput. Without isolation, they mostly increase the speed at which unrelated assumptions meet in one branch.

## Sources

1.  [Git documentation for multiple worktrees](https://git-scm.com/docs/git-worktree)
    
2.  [Anthropic on harnesses for long running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)