How to Use Git Worktrees for Parallel AI Agent Execution

Git worktrees enable parallel AI agent execution by giving each agent its own isolated working directory and git index while sharing a single object store, preventing file-level conflicts, context contamination, and lock contention when multiple agents operate on the same repository.

When Multiple Agents Share a Repository

Running one AI coding agent on a repository is straightforward. Running three, four, or nine simultaneously introduces failure modes that mirror distributed systems concurrency problems: agents overwrite each other's files, operate on stale views of the codebase, and compete for .git/index.lock. Agents proceed silently on corrupted data rather than surfacing exceptions when they hit these conflicts.

Engineering teams have documented running four or five Claude agents simultaneously, each working on different features in parallel with its own complete environment. One practitioner has also described a system scaling to 371 worktrees. That second example is anecdotal rather than primary technical authority, but it illustrates how the pattern is being used in practice. The enabling mechanism is git worktrees: lightweight checkouts that give each agent complete filesystem isolation without duplicating the repository.

Intent, Augment Code's macOS workspace for agent orchestration, builds on this pattern natively. Each Space creates a dedicated git branch and worktree, specialist agents execute in parallel within isolated directories, and the Coordinator manages merge sequencing after the Verifier validates output against the living spec.

This guide walks through the parallel agent problem, git worktree internals, how worktrees resolve multi-agent file conflicts, how Intent implements the pattern at the orchestration layer, how worktrees compare to alternative isolation strategies, and practical patterns for production use.

The Parallel Agent Problem: Four Failure Modes

When multiple AI coding agents operate simultaneously on the same repository, they reproduce concurrency problems from distributed systems with an additional danger: agents do not notice when something goes wrong. Each failure mode scales with participant count regardless of whether participants are humans or language models.

Concurrent File Overwrites

The most immediate failure is simultaneous writes to the same file, where one agent's changes silently overwrite another's. Multi-agent coding conflicts in shared repositories typically go undetected until patches merge, at which point standard git conflict detection compares divergent commits against a common ancestor. Concurrent in-memory writes to the same working directory fall outside this mechanism entirely.

Context Contamination and Cascading Breakage

Each AI agent operates within its own context window with no automatic visibility into changes made by other agents. Agent A's changes can invalidate Agent B's assumptions without Agent B receiving any signal. Google's documentation on multi-agent patterns explicitly addresses this: although parallel agents operate in separate execution threads, they share session state, requiring each agent to write data to a unique key to prevent race conditions.

This contamination compounds when agents work on interdependent code. If Agent A completes a service refactor while Agent B is mid-way through building a consumer of that service, Agent B's work builds on assumptions that are already stale. The resulting breakage is difficult to root-cause because both agents' outputs may look correct in isolation; the failure only surfaces when their changes combine. Shared staging environments amplify this: multiple agents pushing partial changes can destabilize the environment, and teams may spend hours tracing which agent's output introduced the inconsistency.

Race Conditions on Shared Infrastructure

Beyond file-level conflicts, agents sharing mutable state, such as build caches, test databases, and configuration registries, reproduce classical race conditions. Block built an agent task queue specifically to address this: when multiple AI agents work on the same machine, they independently trigger expensive operations like ./gradlew test. The resulting resource thrashing slows all agents. The tool coordinates expensive operations across agents using a FIFO task queue to prevent them from running concurrently.

Git Lock Contention

Git uses file-based locking (.git/index.lock, .git/config.lock) to protect repository integrity. When two agents attempt concurrent git operations on the same working directory, the second agent receives a fatal error:

fatal: Unable to create '/path/to/repo/.git/index.lock': File exists.

Another git process seems to be running in this repository, e.g.
an editor opened by 'git commit'. Please make sure all processes
are terminated then try again. If it still fails, a git process
may have crashed in this repository earlier:
remove the file manually to continue.

Most AI agents do not recover from this error gracefully. Some retry and succeed if the lock clears quickly; others abort the current operation and continue generating code without committing. This leaves unbounded uncommitted state in the working directory. If an agent process crashes while holding the lock, the stale .git/index.lock file persists and blocks all subsequent git operations across every agent until someone removes it manually with rm -f .git/index.lock. In a multi-agent workflow, a single stale lock can freeze all progress until a human intervenes.

What Git Worktrees Are: Lightweight Checkouts Sharing .git

Git worktrees allow a single repository to support multiple working trees, each checking out a different branch simultaneously. The worktree documentation defines the mechanism: the working tree created by git init or git clone is the main working tree, and additional working trees created with git worktree add are linked working trees.

The Two-Pointer Architecture

A linked worktree shares everything with the repository except per-worktree files: HEAD, index, and per-worktree logs. Two internal variables govern the split between private and shared state:

• $GIT_DIR points to the private directory for that worktree, for example, /path/main/.git/worktrees/test-next, holding its own HEAD, index, and per-worktree refs
• $GIT_COMMON_DIR points to the main worktree's $GIT_DIR, for example, /path/main/.git, routing all shared data back to the single canonical .git directory

Fetching in one worktree or renaming a branch in another makes those changes immediately visible to all worktrees because they operate on the same underlying data.

The Branch Exclusivity Constraint

Git prevents the same branch from being checked out in more than one worktree simultaneously by default. Because each worktree's HEAD points to a branch ref, allowing two worktrees to hold the same branch would create conflicting write access to that ref. The worktree documentation defines this as a default safeguard overridable with --force, though no configuration option disables it permanently. Standard workarounds include creating a new branch with -b <new-branch> or checking out in detached HEAD state with --detach.

The Physical Layout

A linked worktree's directory contains a .git file, not a directory, pointing back to the main repository:

gitdir: /home/user/myrepo/.git/worktrees/thanos

Inside the main .git directory, a worktrees/ subdirectory stores metadata for each linked worktree:

.git/worktrees/
└── thanos
    ├── commondir    ← contains "../.." (relative path back to $GIT_COMMON_DIR)
    ├── gitdir       ← absolute path back to linked worktree's .git file
    ├── HEAD         ← this worktree's own HEAD
    ├── index        ← this worktree's own staging area
    ├── logs/
    │   └── HEAD
    └── ORIG_HEAD

Repository history is never duplicated across worktrees. Storage cost scales with working file count, not repository history size. Creating a worktree is often faster than cloning because git worktree add creates a new working tree that shares the existing repository objects instead of fetching a separate copy.

Why Worktrees Solve Multi-Agent File Conflicts

Git worktrees address the parallel agent problem by giving each agent its own complete working directory and git index while sharing a single object store. Each agent operates on its own branch, in its own filesystem path, with no possibility of direct file-level collisions during active work.

Isolation Without Duplication

Each worktree gets a private HEAD, private index, and private working directory. Agent A's uncommitted edits in /project/.trees/TASK-123/ are invisible to Agent B working in /project/.trees/TASK-456/. Git lock contention disappears because each worktree's staging operations target its own index file, not a shared .git/index.lock.

The shared object store means this isolation costs minimal disk space. Only working-directory files are duplicated; the repository's entire commit history, all branch refs, and all remote tracking information exist in a single location.

Conflicts Deferred to Merge Time

Git worktrees provide file isolation without removing conflicts when multiple agents touch the same functionality. Practitioner discussion in a Cursor thread highlights this operational nuance: the conflict problem moves to the PR merge stage. Standard git conflict detection, diff tooling, and rebase workflows handle these deferred conflicts at merge time, where they surface as visible git conflicts instead of silent runtime overwrites.

Converting invisible runtime corruption into standard git conflicts that existing tooling can detect and resolve is the core benefit. The same discussion also notes a practical advantage: isolated context windows reduce the risk of garbage from the main thread contaminating sub-agent reasoning.

Verification Gates Before Merge

The worktree pattern creates a natural checkpoint between agent execution and code integration. The most valuable practice is establishing a clean test baseline before the agent starts work.

The workflow is: create the worktree, run npm lint and npm test immediately, confirm the suite passes green, then hand the worktree to the agent. After the agent finishes, run the same suite again. Any new failures are attributable to agent changes rather than pre-existing issues, because the baseline proves the test suite was passing before the agent touched anything. Without this step, teams waste time investigating whether a test failure is a regression the agent introduced or a flake that was already present on main.

Community discussion in a worktree thread describes a similar principle: catching drift at the integration point rather than during active work. The worktree boundary naturally enforces this by making the "before agent" and "after agent" states easy to diff against a known-good starting point.

How Intent Implements Worktrees for Multi-Agent Orchestration

Intent implements a production multi-agent architecture built on git worktrees, with structured agent roles, a living spec as the coordination artifact, and the Context Engine providing shared codebase understanding across all agents.

Spaces: One Worktree Per Isolation Unit

When a developer creates a prompt in Intent, the application creates a Space with its own dedicated git branch and worktree. The physical layout follows a sibling-directory pattern:

~/code/myproject/            ← main repository
~/code/myproject-feature-a/  ← worktree for Space A
~/code/myproject-feature-b/  ← worktree for Space B

The mapping is 1:1: one logical Space equals one git worktree equals one dedicated branch. All worktrees share the same .git directory through standard git worktree behavior, avoiding repository object duplication while each Space maintains its own working-directory state. Multiple specialist agents can execute concurrently on separate branches without cross-contaminating each other's changes.

The Three-Tier Agent Architecture

Intent structures agent roles into three tiers with explicit separation of concerns, each mapped to a distinct phase of the development lifecycle.

Tier 1: Coordinator Agent. The workflow emphasizes planning and review before implementation begins. After approval, the Coordinator decomposes the spec into tasks with dependency ordering and delegates to specialist agents in coordinated waves as described in the Intent documentation. The Coordinator manages alignment and handoffs, delegating all code writing to specialist agents.

Tier 2: Specialist Agents (Implementors). Six built-in specialist personas handle distinct functions:

Specialists execute in parallel, each in their own context within an isolated git worktree. The Coordinator fans work out to multiple implementor agents running in waves.

Tier 3: Verifier Agent. A distinct agent role functioning as a quality gate. The Verifier checks results against the spec to flag inconsistencies, bugs, or missing pieces, operating after specialists complete their work and before the developer's review. For smaller tasks, multi-agent separation scales dynamically: the Coordinator may auto-validate through its own routines rather than spawning an independent Verifier instance.

The Living Spec as Coordination Artifact

The Spec is the shared coordination artifact all agents and the developer read from and write to. It functions as a self-maintaining document serving as a running summary of the project. When an agent completes work, the Spec reflects the current state. When requirements change, updates propagate to all active agents. Developers can stop the Coordinator at any time to manually edit the Spec.

The Spec serves as the source of truth that agents continuously reference, keeping all participants aligned as the implementation progresses. Engineers define intent and constraints; agents explore the implementation space.

The living spec pattern works best for features with well-defined boundaries where the desired behavior can be expressed declaratively. Exploratory or research-heavy tasks, where requirements emerge during implementation, may cause the Spec to drift as agents update it with conflicting discoveries. In these cases, developers should checkpoint the Spec between execution waves and manually resolve directional disagreements before the next wave begins, rather than relying on auto-propagation to keep agents aligned through ambiguity.

The Context Engine: Shared Codebase Understanding

All agents in Intent share Augment Code's Context Engine, which maintains a real-time semantic index of the entire codebase and processes repositories of 400,000+ files through semantic dependency analysis. Whether the Coordinator is planning work or specialists are executing tasks, agents access the same codebase understanding through this layer. The Context Engine prevents the architectural blind spots that cause agents to make locally correct but globally incompatible changes.

End-to-End Flow

The full workflow from developer prompt to merged code follows a structured sequence with human checkpoints at two stages.

The workflow is not strictly linear. At Step 3, if the developer rejects or substantially rewrites the Spec, the Coordinator re-plans decomposition from the revised starting point. At Step 5, if a specialist fails mid-task (syntax error, test failure, or timeout), Intent surfaces the failure in the workspace; the developer can intervene, adjust the Spec, or re-run that task without restarting the entire wave. At Step 6, if the Verifier flags inconsistencies, the developer reviews the violations and decides whether to loop specific tasks back for correction or manually resolve the issues before proceeding to merge.

Intent also supports BYOA (Bring Your Own Agent): the application works with agents such as Claude Code, Codex, and OpenCode in addition to Augment's native Auggie agent. When using third-party agents, the Coordinator still drafts the living spec, the external agent receives decomposed task assignments, and Intent handles concurrent work through isolated worktrees.

Isolation Strategy Comparison: Worktrees vs. Alternatives

Git worktrees occupy a specific point in the isolation design space. Understanding where worktrees excel and where alternative strategies fit requires examining five dimensions: storage efficiency, creation speed, filesystem isolation, runtime isolation, and dependency handling.

Comparison Matrix

The following matrix compares five isolation strategies across the dimensions most relevant to parallel agent workflows.

Where Worktrees Win

Git worktrees provide the best cost-to-isolation ratio for code-only parallel agent workflows. Creating a worktree takes seconds because only the working tree is checked out; the entire commit history and object database remain shared. For teams running three to five parallel agents on code generation tasks, worktrees provide sufficient isolation with minimal overhead.

The branch exclusivity constraint enforced by Git's worktree specification is a structural advantage in agent workflows: Git refuses to check out the same branch in two worktrees, a rule intended to prevent index and working tree corruption.

The two simpler alternatives fall short in specific ways. Sequential git checkout between branches is incompatible with parallelism: only one branch can be active at a time, and switching requires stashing or committing all in-progress work. Separate git clone operations provide full directory isolation but duplicate the entire object store per clone. For repositories with substantial history, this means more disk usage and longer creation times than worktrees require.

Where Docker Wins

Docker containers provide runtime isolation through Linux namespaces and cgroups that worktrees cannot match. When agents need to run development servers, interact with databases, or bind to network ports, two agents in separate worktrees will still collide on port 3000. Docker's namespace isolation prevents port conflicts in this class.

One practitioner team chose Docker for portability and future cloud execution capability, despite higher resource consumption. That source functions as a practitioner implementation example rather than primary authority for Docker internals.

The Runtime Isolation Gap

Multiple independent sources identify the structural limitation where git worktrees solve file-level conflicts but expose runtime conflicts. One analysis frames the issue directly: worktree isolation stops one task from trampling another's files, but does not stop one task's runtime from trampling another's ports, databases, caches, secrets, or test state.

The emerging composite pattern combines worktrees for git isolation with lightweight runtime isolation for full-stack agents. Dagger's Container-Use tool, as documented by InfoQ, combines git worktrees with container isolation to address this gap.

Practical Patterns for Production Worktree Workflows

Practitioners have described a variety of ways to use git worktrees in multi-agent workflows, rather than a single standard implementation stack. The following patterns represent documented, production-tested approaches.

Worktree-Per-Task vs. Worktree-Per-Agent

The fundamental architectural decision is whether a worktree belongs to a task or an agent identity.

Worktree-per-task (recommended default): Each task gets its own branch and worktree. Agents are assigned to worktrees; worktrees are not permanently owned by agents. This pattern is confirmed in production at incident.io, where the engineering team runs parallel feature agents on different features simultaneously.

Worktree-per-agent suits persistent, specialized agents that maintain their own workspace throughout a session. The agent-workspace project implements this model, launching agent sessions per worktree in either Docker or host mode. This model works for long-running specialist agents like a dedicated test writer or refactoring agent.

The decision heuristic: use worktree-per-task when agents are ephemeral and tasks complete in under an hour, since the worktree is created, used, and destroyed with minimal overhead. Use worktree-per-agent when agents persist across multiple tasks in a session and benefit from warm dependency caches, pre-configured environment state, or accumulated context that would be expensive to rebuild per task.

Git's branch exclusivity constraint means a branch can be checked out in only one worktree at a time by default, unless --force is used.

Worktree Creation and Bootstrap

A production worktree creation script follows common Git worktree automation patterns:

#!/usr/bin/env bash
# create-agent-worktree.sh
# Usage: ./create-agent-worktree.sh <task-id> [base-branch]

set -euo pipefail

TASK_ID="${1:?Usage: $0 <task-id> [base-branch]}"
BASE_BRANCH="${2:-main}"
REPO_ROOT="$(git rev-parse --show-toplevel)"
TREES_DIR="${REPO_ROOT}/.trees"

sanitize_branch_name() {
  echo "$1" | sed 's/[^a-zA-Z0-9-]/-/g' | cut -c1-50
}

BRANCH_NAME="agent/$(sanitize_branch_name "${TASK_ID}")"
WORKTREE_PATH="${TREES_DIR}/${TASK_ID}"

mkdir -p "${TREES_DIR}"
grep -qxF '.trees/' "${REPO_ROOT}/.gitignore" \
  || echo '.trees/' >> "${REPO_ROOT}/.gitignore"

git fetch origin "${BASE_BRANCH}"
git worktree add -b "${BRANCH_NAME}" \
  "${WORKTREE_PATH}" "origin/${BASE_BRANCH}"

cd "${WORKTREE_PATH}"
npm ci --prefer-offline

[ -f "${REPO_ROOT}/.env.local" ] && cp "${REPO_ROOT}/.env.local" .env.local

PORT=$(( 3100 + $(echo "${BRANCH_NAME}" | cksum | cut -d' ' -f1) % 6899 ))
echo "DEV_PORT=${PORT}" >> .env.local
echo "Ready: cd ${WORKTREE_PATH} (port ${PORT})"

The deterministic port assignment via branch name hashing, described in a Vibe Hackers post, gives each worktree a stable port in the 3100-9999 range. That source supports the implementation example rather than a broader standards claim.

Handling Shared Dependencies

Dependencies like node_modules are neither shared nor automatically created in new worktrees. Practitioner documentation from Upsun discusses this as a common workflow limitation. Four strategies address it with distinct tradeoffs:

1. Symlink (conditional): Only safe when package-lock.json is byte-identical between worktrees. Link main worktree's node_modules into the new worktree.
2. Copy-on-write (macOS APFS only): cp -c ../main/node_modules ./node_modules provides near-zero upfront cost, copying bytes only on write. Not portable to Linux.
3. npm workspaces (monorepo): All worktrees share a single top-level node_modules via workspace resolution.
4. Offline cache install (safe default): npm ci --prefer-offline uses npm's shared user-level cache, making subsequent installs faster than cold installs.

Start with npm ci --prefer-offline as the default; it works across all platforms and avoids lockfile parity assumptions. Move to symlinks only when install time exceeds the agent's task duration and you can guarantee package-lock.json is identical across worktrees. Use copy-on-write only on macOS teams willing to accept the Linux portability limitation.

For repositories with massive dependency trees, one practitioner recommends maintaining a fixed pool of pre-warmed worktree slots rather than creating and destroying worktrees per task.

Merge Strategies After Agent Completion

A common rebase-before-merge practice, documented by practitioners, is to rebase a feature branch on the latest main before merging. Each merge incorporates all prior merges, and conflicts surface as normal git conflicts at merge time.

For larger-scale agent fleets, the Overstory framework implements a FIFO merge queue with four-tier conflict resolution, plus a tiered watchdog system for fleet health monitoring.

Cleanup and Lifecycle Management

Prefer git worktree remove over rm -rf. Deleting a worktree via the filesystem can leave stale metadata in .git/worktrees/ until it is cleaned up automatically or by running git worktree prune.

# Clean removal (directory + git metadata)
git worktree remove .trees/TASK-123

# Force remove with uncommitted changes
git worktree remove --force .trees/TASK-123

# Prune stale metadata from manually deleted worktrees
git worktree prune --verbose

# For repos used exclusively for ephemeral agent worktrees
git config gc.worktreePruneExpire now

The automated cleanup script below removes worktrees whose branches have been merged to the remote. Run it as a post-merge CI step or as a scheduled cron job (daily is sufficient for most teams). One edge case: if a worktree was locked with git worktree lock (as shown in the Quick-Start Checklist), git worktree remove --force will still fail. Unlock locked worktrees explicitly before running automated cleanup, or filter them out with git worktree list --porcelain | grep -A1 "^worktree" | grep -B1 "locked".

#!/bin/bash
git fetch origin main

git worktree list --porcelain \
  | grep "^worktree " \
  | awk '{print $2}' \
  | while read -r path; do
  [ "${path}" = "$(git rev-parse --show-toplevel)" ] && continue
  branch=$(git -C "${path}" branch --show-current 2>/dev/null || echo "")
  if [ -n "${branch}" ]; then
    if git merge-base --is-ancestor "${branch}" origin/main 2>/dev/null; then
      echo "Removing merged worktree: ${path} (${branch})"
      git worktree remove "${path}" --force
      git branch -D "${branch}" 2>/dev/null || true
    fi
  fi
done
git worktree prune

Task Decomposition as a Prerequisite

Worktree isolation improves parallel execution for independent tasks but cannot resolve file-level dependencies between agents running concurrently. Practitioner discussion identifies this as a structural prerequisite: if Agent A builds the API and Agent B builds the frontend calling that API, and Agent B needs Agent A's endpoint signatures while working, worktree isolation will not help. These tasks need to be sequenced, not parallelized.

Intent addresses this at a higher orchestration layer through its Coordinator, which plans execution flows with dependency ordering. Tasks that depend on each other are sequenced; genuinely independent tasks run in parallel.

Quick-Start Checklist

# 1. Add worktree container to .gitignore
echo '.trees/' >> .gitignore

# 2. Create your first agent worktree
git worktree add .trees/TASK-123 -b agent/TASK-123 origin/main

# 3. Install dependencies
cd .trees/TASK-123 && npm ci --prefer-offline

# 4. Lock the worktree while agent is running
git worktree lock --reason "Agent running" .trees/TASK-123

# 5. Monitor all active worktrees
git worktree list --porcelain

# 6. Unlock and remove when done
git worktree unlock .trees/TASK-123
git worktree remove .trees/TASK-123
git worktree prune

Limitations and Edge Cases

Git worktrees solve file-level isolation effectively, but production agent workflows encounter several documented edge cases.

Submodule incompatibilities. Each worktree receives its own submodule set, multiplying disk usage. Run git submodule update --init --recursive explicitly inside each new worktree. Where possible, prefer git subtrees or direct vendoring over submodules in repos intended for multi-agent worktree workflows.

No cross-worktree conflict warnings. Git worktrees have no mechanism to warn when two worktrees modify the same files on different branches. Practitioner documentation from Upsun notes that parallel agents touching the same files create integration problems with no tooling-level warning. Assign agents to strictly non-overlapping file domains before work begins, and enable git rerere (git config rerere.enabled true) so conflict resolutions are recorded and reapplied automatically on recurrence.

Shared git hooks across worktrees. Git hooks live in .git/hooks/, which all worktrees share via $GIT_COMMON_DIR. A pre-commit hook configured with Husky or lint-staged executes in every worktree's context. The hook's assumptions about working directory layout, installed binaries, or node_modules paths may not hold in a freshly created worktree that has not yet run npm ci. If hooks fail in new worktrees, either ensure the bootstrap script installs dependencies before the first commit, or configure core.hooksPath per-worktree using extensions.worktreeConfig to point each worktree at its own hooks directory.

IDE support gaps. JetBrains IDEs shipped first-class Git worktree support in the 2026.1 release (March 2026), with EAP builds during the build cycle requiring a registry key. VS Code added worktree support in July 2025. Treat CLI commands (git worktree list, git status) as the authoritative view of worktree state when working with older IDE versions or plugins that may not fully reflect worktree status.

Large repository performance. While worktrees share the object store, each requires a complete working directory checkout. In monorepo contexts, disk I/O compounds with file watchers, test runners, and build tools operating within each worktree simultaneously. Combine git worktree add with git sparse-checkout set <paths> to constrain checkouts to files each agent actually needs.

Implement Worktree-Based Agent Isolation This Sprint

The parallel agent problem is a concurrency problem, and git worktrees provide a lightweight isolation primitive that makes it tractable. Worktrees convert silent runtime file corruption into visible merge-time conflicts, which is the prerequisite for every other coordination strategy: verification gates, test automation, dependency ordering, and spec-driven alignment.

Git worktrees add seconds of setup per agent and working-directory-level disk cost in exchange for eliminating an entire class of silent, cascading failures that can corrupt hours of agent output. Production teams and open-source tools have validated the pattern using worktrees as the underlying isolation primitive.

For teams ready to move beyond manual worktree scripting, Intent automates the full lifecycle: the Coordinator handles task decomposition with dependency ordering through the Context Engine, specialists execute in parallel across isolated worktrees, and the Verifier validates output against the living spec before merge.

FAQ

Related

• How to Run a Multi-Agent Coding Workspace (2026)
• What Is Spec-Driven Development? A Complete Guide
• Single-Agent vs Multi-Agent AI: When to Scale Your Dev Workflow
• Intent vs Claude Code (2026): Terminal Power Meets Multi-Agent Orchestration
• 6 Best Devin Alternatives for AI Agent Orchestration in 2026