Parallel coding agents clash over files: split by ownership

Running several coding agents in parallel only pays off when the tasks are already separate. Give each agent its own files and an agreed shared interface, then isolate it in its own git worktree, branch or cloud task. Merge one branch at a time with tests after each merge, or extra agents can leave you more coordination work than progress.

This is part 13 of a series on AI-assisted engineering. Claude Code is the worked example. The tool behaviour below comes from each tool’s official docs and the git worktree docs, last verified on 11 October 2026. None of it was tested for this post. When a sub-agent is the right tool at all, rather than a skill, is covered in Part 3.

Parallel agents help when the tasks don’t touch

Parallel work suits tasks that don’t need each other, such as read-only research or separate modules with their own files. It hurts when two agents need the same file, or when one task needs the other’s output first. An interface that is still unclear hurts too.

Claude Code’s agent teams docs draw the same line: “For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective.” The same page suggests starting with research and review: tasks “that have clear boundaries and don’t require writing code”. Read-only work can’t produce a merge conflict, so it is a low-risk place to start.

Parallel work also costs more than it looks. Claude Code’s parallel agents overview notes that “Running several sessions or subagents at once multiplies token usage”. The agent teams page adds that more teammates bring more “communication, task coordination, and potential for conflicts”. And every extra agent is one more diff for you to read.

Split the work by ownership, and agree the interface first

A parallel split works when each agent owns a clear set of files and the places where their work meets are fixed before they start. Split by ownership, not by step: “the API agent owns src/api/orders/” is a lane, while “agent 2 writes the tests after agent 1 finishes” is a queue.

An example split for an order history feature, with an API, a screen and a shared type between them:

The shared type is the interface. Write it first, review it, and commit it to the branch both agents will start from:

// Example contract, agreed before the parallel work starts.
export interface OrderSummary {
  id: string
  placedAt: string // ISO 8601 date
  total: number
  currency: string
  status: 'open' | 'paid' | 'refunded'
}

Neither lane may change that file. If one agent finds the contract is wrong, it stops and reports, and the contract change happens once, on the base branch, before work continues. Two agents each “fixing” the contract in their own branch is how you get two contracts.

Ownership matters even more when the tool doesn’t isolate files for you. Claude Code’s agent teams, for example, don’t put teammates in separate worktrees, and the docs on how to avoid file conflicts warn: “Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files”. Finding the real boundaries in a codebase before you split it is the subject of Part 8.

Give every agent its own worktree, branch or cloud task

A git worktree is a second working folder for the same repository, with its own checked-out branch. In the words of the git worktree docs, a repository “can support multiple working trees, allowing you to check out more than one branch at a time”. Each new worktree shares “everything except per-worktree files such as HEAD, index, etc.” So two agents in two worktrees edit two copies of the files, and their commits land in the same repository.

An example of setting up two lanes by hand, from the main checkout:

# one worktree and one new branch per lane
git worktree add ../shop-orders-api -b orders-api
git worktree add ../shop-orders-ui -b orders-ui

# see every worktree and the branch it has checked out
git worktree list

# after the branch is merged
git worktree remove ../shop-orders-api

One branch fits in one worktree. By default, git worktree add “refuses to create a new worktree” when the branch “is already checked out by another worktree”. Give each agent its own branch.

A new worktree is also missing things. Claude Code’s worktree docs call it “a fresh checkout”, so dependencies need installing there. Gitignored files such as .env don’t come along unless you list them in a .worktreeinclude file.

Only the files are separate. A local database, a dev server port or a shared cache outside the folder is still shared by every agent. Plan for that before two agents run migrations against the same database.

In Claude Code, claude --worktree orders-api creates the worktree under .claude/worktrees/orders-api/ on a new branch called worktree-orders-api, and starts the session there. There is a trap for the interface-first split: by default, new worktrees “branch from the repository’s default branch on the remote”. A contract you committed only on your machine isn’t in that base. Push it first, or set worktree.baseRef to "head" so worktrees branch from your local HEAD (choose the base branch).

Worktree isolation also has an edge. In a worktree session, Claude Code blocks edits and git commands aimed at the main checkout. But the same page says a command “such as cp or a shell redirect” that writes there without running git “isn’t refused by them”. What an agent may do outside its folder is a permissions question, covered in Part 6.

Parallel work and isolation in seven coding agents

All seven agents below can run work side by side. They differ in where the copy lives and how the result comes back:

Each row comes from the linked docs, last verified on 11 October 2026; none was tested for this post.

Gemini CLI’s docs also note that for unpaid tier and Google One users, Gemini CLI was replaced by Antigravity CLI on 18 June 2026.

Most of these use git worktrees for local work: Claude Code, the Codex app, Cursor, Gemini CLI, Windsurf and Antigravity. Codex cloud and Copilot cloud agent give each task its own cloud environment instead. In every tool, isolation stops at the copy, and bringing the work back together is a separate step.

Merge one branch at a time, and test what you merged

Isolation only delays the moment the work meets. Integration is where parallel work succeeds or fails. Treat it as its own task, and merge one branch at a time in an order you choose.

contract on base → lane A merged → full checks → lane B merged → full checks

A textual conflict is the kind git catches: both branches changed the same lines, so git stops and shows you both sides. The harder kind merges cleanly and still breaks, because each branch was correct alone and wrong together. That is why each lane’s own green tests are not enough. Run the full test suite, lint, type checks and the build after every merge, on the combined code. Turning those checks into CI gates is the subject of Part 10.

Decide who resolves conflicts before the first one appears. Pick one owner: you, or one named agent working from both branches’ intent. Never let two agents each resolve the same conflict in their own branch. Copilot cloud agent keeps the final step with a person. Its pull requests “must be reviewed and merged by a human”, and it “cannot approve or merge a pull request” (risks and mitigations). Reviewing agent-written diffs by risk is Part 11.

Clean up after the merge. git worktree remove only removes a worktree with “no untracked files and no modification in tracked files” unless you force it. The tools differ too. Claude Code removes a clean worktree from an unnamed session when you exit (worktrees). Gemini CLI “does not automatically delete” its worktrees, so old branches and folders pile up unless someone removes them.

Three prompts: split, work in a lane, integrate

The three prompts follow the split, lane and merge steps in order. None relies on a tool-specific feature; where your agent has a plan or read-only mode, run Prompt 1 there.

Prompt 1: split the work

Use Prompt 1 before you start any parallel agents; it plans the split and stops.

Task: <describe the task>

Before any code is written, decide whether this task should be
split across parallel coding agents.

Inspect only the parts of the repository this task touches.
Do not edit any files yet.
Never print, expose or commit secret values.

1. List the pieces of work the task needs.
2. For each piece, name the files or folders it would change.
3. Mark which pieces share files, and which depend on another's output.
4. Name every interface between pieces: types, API contracts,
   database schema, events, config.
5. Recommend one of:
   - one agent, working in sequence
   - parallel read-only research, then one agent implements
   - parallel agents, one per piece
6. For parallel agents, give each piece:
   - the files it may change
   - the files it must not change
   - the interface it depends on, and who defines it
   - the checks that prove it works

If two pieces need the same file, or one needs another's output,
keep them in one piece or run them in sequence.
If the benefit of splitting is unclear, recommend one agent.

Do not commit, push, create branches or worktrees, run destructive
commands or make external changes unless I explicitly authorise it.
If two reasonable attempts fail, stop and report the failure rather
than repeatedly guessing.

Then stop and wait for my approval.

Prompt 2: work in your lane

Paste Prompt 2 into each parallel agent, already started in its own worktree or branch, with that lane’s details filled in.

You are one of several coding agents working in parallel on this
repository, each in its own worktree and branch.

Task: <this lane's piece of the work>
Files you may change: <paths>
Files you must not change: <paths, including the shared interface>
Interface you depend on: <file or contract on the base branch>

- Change only the files you own. If you need a change outside them,
  stop and tell me what and why.
- Do not change the shared interface. If it looks wrong, stop and
  report it.
- Set up only this worktree. Do not touch other worktrees or the
  main checkout.
- Run the tests, lint and type checks for your piece.
- Never print, expose or commit secret values.
- Do not commit, push, merge, deploy, run destructive commands or
  make external changes unless I explicitly authorise it.
- If two reasonable attempts fail, stop and report the failure
  rather than repeatedly guessing.

When done, report:
- files changed
- checks run and their results
- anything you assumed about the other lanes
- anything still unverified

Prompt 3: integrate the branches

Use Prompt 3 once every lane has reported, in a clean checkout of the target branch.

Task: integrate these branches into <target branch>, in this order:
<branch list>

You may merge locally into <target branch>. Nothing else is authorised.
Never print, expose or commit secret values.

For each branch, in order:
1. Show its diff against <target branch> and list any file it
   changes outside its agreed lane.
2. Merge it.
3. On a conflict, do not pick a side. Show both versions, explain
   what each branch intended, propose a resolution and wait for me.
4. After the merge, run the full test suite, lint, type checks and
   build, not only the tests for that lane.
5. Report the results before you move to the next branch.

Do not push, deploy, delete branches or worktrees, run destructive
commands or make external changes unless I explicitly authorise it.
If two reasonable attempts fail, stop and report the failure rather
than repeatedly guessing.

At the end, report:
- branches merged
- conflicts found and how each was resolved
- checks run after each merge, and their results
- anything still unverified

The “wait for me” line in step 3 keeps one owner for every conflict.

A checklist before you run agents in parallel

• The tasks don’t share files, and none needs another’s output.
• Each agent has a written list of files it owns and files it must not change.
• The shared interface is written, reviewed and on the base branch the worktrees start from.
• Every agent has its own worktree, branch or cloud task.
• Each worktree has its dependencies and local config set up.
• Shared resources outside the folder (a database, a port) are planned for.
• One owner resolves conflicts.
• Branches merge one at a time, with the full checks after each merge.
• Finished worktrees and branches get removed.

Quick answers

What is a git worktree?

A git worktree is an extra working folder attached to the same repository, with its own checked-out branch, index and HEAD. It lets you, or a coding agent, work on two branches at once without cloning the repository again.

Can two coding agents edit the same repository at the same time?

Two coding agents can work on one repository at the same time when each has its own git worktree, branch or cloud task. Without that isolation, two agents editing the same files in one folder can overwrite each other’s changes.

When should you not run coding agents in parallel?

Coding agents should not run in parallel when the tasks edit the same files or when one task needs another’s output. An interface nobody has agreed yet is another reason to wait. A single agent working in sequence is simpler for those cases.

Do git worktrees prevent merge conflicts?

Git worktrees keep each agent’s edits apart while it works, but they don’t prevent merge conflicts. The branches still meet when you merge them. Conflicts show up then, and so do changes that merge cleanly but break when combined.

Who should resolve merge conflicts between AI agents?

One owner should resolve each merge conflict. That owner is a person, or one agent given both branches’ intent and told to propose a fix and wait for approval. GitHub Copilot cloud agent, for example, cannot merge its own pull requests; a human must.

More on AI coding is in the AI category.