Why Multi-Agent Parallel Development Works: Git Worktree Isolation and Coordinated Merging

When you want multiple AI agents to work on the same codebase at the same time, the first wall you hit is that they share one working directory and overwrite each other’s files. Git Worktree + coordinator/worker mode exists to solve this. This article explains the principles, why it works, and where the benefits come from.

1. The Problem: Why Multiple Agents Cannot Just Edit Together

A single agent editing code sequentially in one working directory is fine. But once you want multiple agents to work truly in parallel, problems appear:

• They point to the same working directory and branch. Agent A modifies a file, then Agent B overwrites it.
• Git’s index and HEAD are globally shared. If two agents run git add or commit at the same time, history becomes messy.
• No agent knows which files others are touching. Without isolation, there is no real parallelism.

The naive solution is to clone the repository once per agent. This isolates work, but it is expensive: every clone is a full copy, disk and time costs are high, and merging back from scattered independent repos is awkward. Git Worktree is the lightweight answer.

2. Core Principle: What Is Git Worktree?

A normal Git repository has one working directory attached to a branch. worktree lets you check out multiple working directories from the same repository, each attached to a different branch:

flowchart TD
    G[".git object database
history / objects / refs shared"]
    W1["worktree A
branch feature/backend
independent workspace + index + HEAD"]
    W2["worktree B
branch feature/frontend
independent workspace + index + HEAD"]
    W3["worktree C
branch feature/ros2
independent workspace + index + HEAD"]
    G --- W1
    G --- W2
    G --- W3

    style G fill:#dbe9ff,stroke:#2563eb,stroke-width:2px

Two properties matter:

• Shared object database: all worktrees share the same .git object database, including commits, objects, and refs. It is not a clone, so it uses almost no extra space and is created quickly.
• Independent workspace + index + HEAD: each worktree has its own file directory, staging area, and current branch. Editing, adding, and committing in one worktree does not affect another.

In one sentence: Worktree gives you file-system-level physical isolation while sharing the same history. Isolation makes parallel work safe; shared history makes merging simple. Multi-agent parallel development needs both.

Many agent frameworks already support this natively. For example, Claude Code subagents support isolation: "worktree", automatically creating an isolated worktree for each parallel task and cleaning it up afterward.

3. Overall Pattern: Dispatch -> Parallel Work -> Coordinated Merge

This pattern is a coordinator + workers structure with three stages:

flowchart LR
    A["1. Dispatch
main agent splits tasks
creates isolated worktrees"] --> B["2. Parallel execution
subagents develop and commit
inside independent worktrees"]
    B --> C["3. Coordinated merge
main agent checks conflicts
merges sequentially and cleans up"]

    style A fill:#dbe9ff,stroke:#2563eb
    style C fill:#ffe9d5,stroke:#b71d18

Stage 1: Main Agent Dispatches

The main agent is the coordinator. It splits the large task into non-overlapping subtasks, creates an independent worktree and branch for each, then dispatches subagents in parallel.

Stage 2: Subagents Work in Parallel

Each subagent only receives its own working directory and branch. Its scope is limited to a specific file domain, and it is explicitly forbidden from touching other areas. It does not need to know other agents exist. This is crucial:

flowchart TD
    M["Main agent / coordinator"]
    M -->|create env + dispatch| S1["Subagent 1 · backend"]
    M -->|create env + dispatch| S2["Subagent 2 · frontend"]
    M -->|create env + dispatch| S3["Subagent 3 · ros2"]
    S1 -->|commit + summary| M
    S2 -->|commit + summary| M
    S3 -->|commit + summary| M
    M --> R["collect summaries → check conflicts → merge sequentially → clean up"]

    style M fill:#dbe9ff,stroke:#2563eb,stroke-width:2px

“Subagents cannot see each other” is a feature, not a bug. Because there is no shared state, they can work like lock-free concurrent workers: no mutual coordination, no blocking. Coordination complexity is concentrated in the main agent.

Stage 3: Main Agent Merges

After all subagents finish, the main agent returns to the main directory, reviews each branch’s summary, evaluates conflict risk, merges one branch at a time, and then removes the worktrees.

Why merge sequentially? If multiple parallel branches are merged all at once, conflicts blend together and become hard to locate. When merging one by one, each conflict is only “current branch vs. already merged result,” which is smaller and easier to handle. This serializes the uncertainty created by parallel work back into a controlled merge process.

4. How Conflict Handling Works

Conflicts are not avoided by luck. They are reduced by structure:

The underlying rule is simple: conflict probability is proportional to overlap in file domains. Split tasks so file domains naturally do not overlap, and conflicts approach zero.

5. Benefits

This is where the pattern earns its value:

6. When It Fits, and When It Does Not

This pattern is not universal. Its value depends on one premise: the task can be split into subtasks with non-overlapping file domains.

Very suitable when:

• The project is modular, such as backend/, frontend/, and ros2/, so each subagent owns a natural directory.
• Subtasks are weakly dependent and can be completed independently.
• Each task is large enough to justify environment setup and coordination overhead.

Less suitable when:

• Tasks are highly coupled and repeatedly modify the same core files.
• Tasks are tiny and fragmented, so coordination overhead exceeds the parallelism benefit.
• Subtasks have strong sequential dependencies, where B must wait for A. That is a pipeline, not parallel work.

Rule of thumb: first ask whether the file domains overlap. Low overlap means this pattern is valuable. High overlap means refactor first or work sequentially.

7. Best Practices at the Principle Level

These are not command steps. They are constraints that make the pattern work:

1. Split by non-overlapping file domains. This is the foundation. Each subagent needs a clear territory.
2. Shared files belong to the main agent. Files such as docker-compose.yml or public interface definitions should be changed by the coordinator, not by subagents.
3. Define interface contracts first. Before parallel work starts, define API contracts. Otherwise each subagent may invent incompatible interfaces.
4. Keep commits small. Commit each functional unit separately. Small commits make conflict diagnosis and cherry-picking precise.

One-Sentence Summary

The hard part of multi-agent parallel development is that a shared workspace causes agents to step on each other. Git Worktree solves isolation and merging at the same time through “shared history + isolated workspaces.” Add a coordinator/worker structure on top, and you get a development pattern that is truly parallel, low-conflict, reviewable, and scalable. Its power depends on whether you can split the work into non-overlapping file domains.