Use git worktrees with multiple agents without merge hell

You end up with two agents editing the same repository at once, each in their own directory, without file-level conflicts but still stepping on each other’s intent. Worktrees stop the merge hell that happens when two processes write to the same file, but they don’t stop the real problem: two agents forming plans that overlap at the level of goals instead of lines.

What a worktree gives you and what it doesn’t

A git worktree is a separate working directory that shares the same repository history. When you run git worktree add /path/to/worktree branch, you get a clean copy of the code at that branch or commit. Each worktree has its own index and working copy, so two agents running in different worktrees can edit files without overwriting each other’s changes.

Worktrees solve exactly one problem: two processes editing the same files. If you run two agents in the same working copy, they will still step on each other’s file changes and create merge conflicts. Worktrees prevent that by giving each agent a private working space, but they do nothing to prevent two agents from making conflicting decisions about what to build or where to change the architecture.

The model is simple. You create one worktree per agent or per task. Each agent operates in its own directory, writes its own changes, and pushes to its own branch. You can merge the branches later, but you still need a way to know which decisions were made and why. Worktrees keep the files apart; they don’t keep the plans apart.

When worktrees are worth the setup

Worktrees shine when you have two agents that need to touch unrelated parts of the codebase at the same time. For example, one agent updates documentation while another refactors a service. The agents won’t write to the same files, so worktrees prevent file-level conflicts. If the agents work on the same feature or the same module, the worktrees only delay the inevitable merge conflict, they don’t prevent it.

Worktrees also help when you want to test changes in isolation before merging. Each agent can build, test, and polish its work in a private worktree, then push to a branch and open a pull request. The isolation reduces noise in the CI logs and makes it easier to review each change on its own.

What worktrees cannot fix

Worktrees do not solve intent-level conflicts. Two agents can still decide to rename the same class, move the same function, or change the same API contract. The worktrees keep the file changes apart, but the merge conflict appears when you try to combine the branches. Worktrees also don’t capture the reasoning behind each decision, so when a reviewer looks at the final diff they have to reconstruct what each agent intended.

Worktrees don’t help with shared state during the session. If an agent starts a task and later another agent picks it up, there’s no built-in way to see what was already decided or what assumptions were made. The context lives in the agent’s private session, and that context only surfaces at review time when mistakes are expensive.

How to set up worktrees for two agents in practice

Start with a clean repository and a branch for each agent. If you already have a branch you want to use, check it out first. Then create two worktrees, one for each agent. Name the worktrees after the agent or the task so you can keep track of them.

git worktree add /tmp/agent-a main

# Create a branch for agent A if it doesn’t exist
cd /tmp/agent-a
git checkout -b feature/agent-a

# Repeat for agent B in a separate directory
git worktree add /tmp/agent-b feature/agent-a
cd /tmp/agent-b

Each agent now has its own working copy. Agent A can edit files in /tmp/agent-a while agent B edits files in /tmp/agent-b. The two directories share the same repository history, so commits in one worktree are visible in the other, but the working copies are isolated.

Run the agents in their worktrees

Start the first agent in its worktree. Point it at the /tmp/agent-a directory and give it the branch you created. Do the same for the second agent in /tmp/agent-b. Each agent operates in its own space, so they won’t overwrite each other’s files. If you use an MCP-capable agent like Claude Code or Cursor, configure it to use the correct working directory.

Agents often need to call tools or scripts that assume a specific environment. Make sure each agent’s environment variables, configuration files, and tool paths point to the right worktree. If one agent installs dependencies in its worktree, the other agent won’t see those changes, which is usually what you want.

Keep tasks aligned across worktrees

Even with worktrees, two agents can still drift apart if they don’t share their assumptions. Record decisions, scope, and risks in a shared place so both agents know what the other is doing. Without this, you end up with two branches that solve the same problem in different ways, and the merge conflict appears at review time.

One way to keep alignment is to name the worktrees after the tasks they handle. For example, /tmp/add-payment-method and /tmp/fix-login-bug. Then, in each worktree, create a file called TASK.md that lists the goal, the scope, the assumptions, and the decisions made so far. Agents can update this file as they work, and reviewers can read it before merging.

Another approach is to use a shared state layer that agents can read and write while they work. Tools like the five tools let you record intent, decisions, and findings in a workspace that both agents can inspect. When an agent starts a task, it registers its presence and the scope it owns. Other agents see that scope and can avoid stepping on it.

What to do after the agents finish

When both agents finish their work, you have two branches with changes that may overlap at the intent level. The worktrees kept the file changes apart, but you still need to reconcile the plans. Start by reviewing the changes in each branch separately. Look for conflicts in the intent: did both agents rename the same class, change the same API, or update the same configuration?

If the changes are truly independent, merge the branches in either order. If they overlap, you’ll need to reconcile the intent before merging. Use the TASK.md files or the shared state layer to see what each agent intended. Then, decide which approach to keep and which to discard, or combine the two into a single change.

Push each branch and open a pull request. The reviewers can see the changes in isolation and understand the intent behind each one. If you used a shared state layer, include a link to the workspace so reviewers can see the decisions and assumptions that led to the changes.

Merge strategies that reduce pain

Merge the smaller change first. Smaller pull requests are easier to review and less likely to conflict with other changes. If the first merge introduces a conflict, you only have to resolve it once, and the conflict resolution is visible to the second agent before they finalize their work.

Use feature flags to gate changes that affect shared behavior. If both agents change the same API, wrap the new behavior behind a flag and enable it only after both changes are merged and tested. This lets you deploy incrementally and reduces the chance of a breaking change reaching production.

Consider a design review before merging. If the two changes affect the same module or the same architecture, schedule a quick sync to agree on the final shape. The review can happen in the shared state layer or in a separate meeting, but it should happen before the branches are merged.

When worktrees aren’t enough

Worktrees solve the file-level conflict, but they don’t solve the intent-level conflict. If two agents are working on the same feature or the same module, you still need a way to coordinate their plans. The earlier you record decisions and assumptions, the less rework you’ll have to do when you try to merge.

If you find yourself frequently merging branches that conflict at the intent level, consider a shared workspace that agents can use while they work. Tools like the five tools let you register presence, claim tasks, and record decisions before agents start editing files. Overlap warnings arrive when an agent claims work, which the five tools each contribute to in a different way.

Worktrees are also brittle when you need to coordinate across repositories or machines. If an agent starts a task on one machine and another agent needs to continue it on another, worktrees don’t help you transfer the context. A shared workspace that travels with the work, not the machine, is what you need in that case.

For coordination across repositories and machines, Concord Cloud is coming soon. It keeps the work state, decisions, and ownership in one place so agents can hand off tasks without losing context, even when they run on different machines or in different repositories.

Checklist before you run two agents in parallel