Use Git Worktrees to Keep Parallel Coding Agents Isolated

Last reviewed: 2026-05-26

Direct answer

Run each parallel coding agent from its own Git worktree, on its own branch, with a small assignment boundary and a pull request handoff. Git documents git-worktree as the command family for managing multiple working trees, and GitHub documents pull requests as the review path for proposing, discussing, and integrating changes. Treat repository instruction files as part of the same boundary: Codex documents AGENTS.md guidance, and Claude Code documents CLAUDE.md project instructions and memory.

The operating rule is simple: one agent, one worktree, one branch, one task owner, one reviewable handoff. If you need the broader setup pattern first, start with Repository Context and Parallel Agent Workflows. For permission and secret guardrails, see Set Safe Permission and Secret Boundaries for Coding Agents.

For broader release checks, see AI Coding Agent Setup, Security, and Model Routing .

Who this is for

This guide is for maintainers who run two or more coding agents against one repository and need clean ownership, predictable review, and lower risk of agents overwriting each other. It fits terminal agents, IDE agents, and cloud agents as long as the team can map each assignment to a branch and a review path.

It is especially useful when one person is coordinating several small agent tasks, when a team is comparing different agent tools, or when an engineering lead wants repeatable rules before allowing agents to work beyond a local sandbox. The goal is not to make parallel work magically conflict-free. The goal is to make conflicts visible early, keep rollback simple, and give reviewers a clear trail from task brief to branch to pull request.

Key takeaways

• Give every active agent a dedicated worktree path and branch.
• Keep durable repository rules in the instruction file your agent tool supports, then verify the current tool docs before relying on inheritance or precedence.
• Avoid assigning two agents to the same hot files at the same time; if overlap is unavoidable, name one owner and one reviewer before work starts.
• Use a pull request as the handoff point because it gives reviewers a branch, diff, discussion thread, and conflict surface.
• Log the smoke-test result with placeholders and outcomes, not secrets, private prompts, full responses, prices, limits, or availability claims.

Isolation rule set

Start by treating the coordinating checkout as a control plane, not as the place where every agent edits. The coordinating checkout is where you inspect active worktrees, decide which branch belongs to which task, and prepare review handoffs. Each coding agent works somewhere else, in a path named for its assignment or label. That naming convention matters because the path is often the first thing a human checks when a task gets confusing.

A useful assignment record has four fields: agent label, worktree path, branch name, and allowed file set. If any of those fields are missing, the work is not ready to start. The branch name should identify the task rather than the model or vendor. The allowed file set should be narrow enough that a reviewer can tell whether the agent stayed inside the request. If a task really needs broad edits, split discovery and implementation into separate requests so the first agent maps the change and the second agent applies it with a tighter scope.

Keep repository instructions versioned in the repository. For Codex-style workflows, verify the current AGENTS.md behavior in the official docs before depending on nested or inherited rules. For Claude Code workflows, verify the current CLAUDE.md and memory behavior before using it as the source of project policy. The practical point is tool-agnostic: the worktree separates files, but the instruction file explains how the agent should behave inside those files.

Use a preflight check before every assignment. The preflight is not a full quality review. It only answers whether the next agent can start without colliding with another active task.

git status --short
git branch --show-current
git worktree list
git worktree add ../agent-a feature/agent-a
git worktree list

After creating the worktree, hand the agent a short task brief. Keep the brief boring and explicit.

agent_label: agent-a
worktree_path: ../agent-a
branch_name: feature/agent-a
scope: update parser edge case only
allowed_files: src/parser.ext; tests/parser_test.ext
do_not_touch: release configuration; credentials; unrelated modules
checks_to_run: placeholder-check
handoff_required: changed files, commands, result, risks

Smoke-test workflow

Setup assumptions:

• Git is installed and the repository is already cloned.
• The starting checkout has no unrelated uncommitted changes.
• The remote review flow accepts pull requests from feature branches.
• Each agent receives a bounded task brief and a named branch.

Happy-path request plan:

1. Create a branch and worktree for the first agent after verifying current syntax in the Git docs.
2. Give the agent one bounded request: modify the assigned files, run the named check, and summarize the result.
3. From the coordinating checkout, verify that the worktree list shows a distinct path and branch for the agent.
4. Confirm unrelated worktrees remain clean before preparing the review handoff.
5. Open a pull request from the agent branch and include changed files, commands run, and known risks.

Error-path check:

• Before assigning a second agent, compare the planned branch and file list against active worktrees. Fail the assignment if it reuses an active branch or overlaps the same hot files without a named owner and reviewer.

Minimum assertions:

• Each active agent has a distinct worktree path, branch name, task owner, and assigned file set.
• Uncommitted changes do not appear outside the assigned worktree.
• The pull request branch matches the worktree branch.
• A reviewer can reproduce the commands listed in the handoff.

What the smoke test must not assert:

• Do not claim that all continuous integration jobs will pass until those jobs actually run.
• Do not claim final merge safety, model quality, conflict absence, pricing, limits, uptime, or tool availability from this local smoke test alone.

Sanitized log-record template:

worktree_run_id: wt-placeholder-001
agent_label: agent-a
worktree_path: ../agent-a
branch_name: feature/agent-a
assigned_files: src/example.ext; tests/example_test.ext
happy_path_result: PASS|FAIL
error_path_result: PASS|FAIL
checks_run: placeholder-check
pr_url: https://example.invalid/org/repo/pull/123
reviewer_notes: placeholder summary only
decision: hold for human review

Failure modes

Parallel agent work usually fails in operationally boring ways. The dangerous part is that those failures look like normal development until review time. Build the following failure modes into your assignment checklist.

1. Shared branch ownership. Two agents working on the same branch can overwrite, revert, or silently mix each other’s changes. The resulting diff may look like one coherent change even though it contains two unrelated intentions. Prevent this by rejecting any assignment that reuses an active branch name.

2. Wrong-directory execution. An agent or human coordinator can run status checks, edits, or commits from the coordinating checkout instead of the assigned worktree. This breaks the isolation story because the task result is no longer tied to the expected path. Make the first step of every handoff a path and branch confirmation.

pwd
git branch --show-current
git status --short

3. Overlapping hot files. Worktrees separate directories, but they do not remove merge conflicts. If two agents edit the same migration, generated file, lockfile, route table, prompt registry, or central configuration file, the second pull request may inherit a conflict that neither task brief mentioned. Treat hot files as scheduled resources. Assign one owner, one reviewer, and one order of operations.

4. Dirty starting state. If the coordinator starts from a checkout with unrelated changes or a stale base branch, the agent may solve the wrong problem. The pull request can then be technically isolated but semantically stale. Before assigning work, record the intended base branch and update policy. If the base changes during a long task, tell the agent whether to rebase, restart, or stop for review.

5. Instruction drift. One agent may read current repository instructions while another uses stale memory, an outdated local note, or a different tool-specific instruction file. That creates inconsistent style, test, and safety behavior across otherwise isolated worktrees. Keep durable rules in the repository, and ask each agent to name the instruction source it followed in the handoff.

6. Secret and environment leakage. A worktree path is still a real working directory. If an agent copies local credential files, private prompts, personal notes, or environment dumps into the branch, isolation has failed even if the code diff is small. Keep sensitive files out of the task scope and require the handoff log to use placeholders rather than real secret values.

7. Orphaned worktrees and reserved branches. A half-finished task can leave a worktree directory, branch, or lock behind. Later coordinators may assume the branch is still active, or worse, reuse the path without understanding its history. Close each task with an explicit keep, remove, or archive decision after review.

8. Pull request handoff without reproduction details. A branch alone is not enough. If the pull request does not include changed files, commands run, failing checks, skipped checks, and known risks, the reviewer has to rediscover the task. That slows review and makes agent output look less trustworthy than it is. Require a short handoff every time, even for small changes.

9. Generated-file churn. Agents often touch generated artifacts, dependency lockfiles, snapshots, or formatted files while solving a narrow request. In separate worktrees, that churn may not be obvious until the pull request diff appears. Decide before work starts whether generated outputs are allowed, required, or forbidden for the task.

10. Review queue collision. Parallel work can produce several clean branches that all depend on the same base assumption. If reviewers merge them in the wrong order, the final repository state may differ from what later agents tested. Use pull requests as the sequencing surface, and mark dependencies between related branches before merge decisions.

Sources checked

• Official Git worktree reference - accessed 2026-05-26; purpose: verify that git-worktree manages multiple working trees and that command syntax should be checked before scripting.
• GitHub pull requests documentation - accessed 2026-05-26; purpose: verify pull requests as the review and change-discussion handoff surface.
• OpenAI Codex AGENTS.md documentation - accessed 2026-05-26; purpose: verify Codex instruction-file guidance before making tool-specific repository rule claims.
• Claude Code memory documentation - accessed 2026-05-26; purpose: verify Claude Code guidance for CLAUDE.md project instructions and memory.

Contract details to verify

FAQ

Can two agents share one worktree?

Avoid it for parallel work. A separate worktree per agent makes ownership, status, rollback, and review easier to inspect. Sharing a worktree also makes it harder to tell which agent changed which file, which instruction set was followed, and which command output belongs to which task.

Does a worktree replace code review?

No. A worktree narrows change ownership; the pull request still carries the review discussion, checks, and merge decision. Think of the worktree as the workspace boundary and the pull request as the decision boundary.

Should every agent get a separate clone instead?

A separate clone can work, but worktrees keep multiple working directories attached to one repository. Choose the policy your team can audit consistently. If your team already uses separate clones, keep the same isolation principles: one branch, one assignment, one reviewable handoff.

Where should tool-specific instructions live?

Use the instruction file your agent tool documents, keep the rules versioned with the repository, and verify current behavior in the official docs before relying on precedence or inheritance. The key is not the filename alone. The key is that the coordinator, agent, and reviewer can all inspect the rule source.

What should happen after a pull request merges?

Close the loop. Record whether the worktree should be kept for follow-up, removed after merge, or archived for investigation. Do not leave old worktrees around without an owner, because stale directories make later branch and file ownership harder to reason about.

Reader next step

Turn the next coding-agent request into a one-page task brief, then compare it with Write Coding Agent Task Briefs That Produce Reviewable Changes. When the branch is ready for review, use How to Hand Off Coding Agent Pull Requests for Review to make the handoff reproducible.

Use AI Coding Agent Setup, Security, and Model Routing as the next comparison point. Keep Set Safe Permission and Secret Boundaries for Coding Agents nearby for setup and permission checks.