How to Run Parallel AI Coding Agents Without Merge Conflicts (The Git Worktree Playbook)

You have three AI coding agents available to you right now. Claude Code is exceptional at deep, multi-file refactors. Codex churns through test generation with mechanical precision. Gemini CLI can hold your entire codebase in context and produce documentation that actually reflects what the code does. Running them one after another is leaving serious speed on the table — a sequential pipeline that could take four hours collapses to under ninety minutes when all three run in parallel.

The problem is that naive parallelism is worse than no parallelism at all. Drop three agents into the same working directory and you get a race condition on package.json, conflicting edits to tsconfig.json, and a merge history that looks like it was authored by a committee during a fire drill. A 2025 survey of developer teams using AI coding tools found that 41% reported losing work to agent miscoordination — not to bad code, but to agents stepping on each other's changes.

This guide solves that problem end to end. You will learn how to run parallel AI coding agents without merge conflicts using Git worktrees as the isolation primitive, a three-layer workspace stack to keep agents fully separated, and Medley.sh as the orchestration layer that manages the queue, surfaces blockers, and sequences merges so you never have to babysit a terminal again.

Why Parallel Agents Conflict

Before reaching for a solution, it is worth being precise about the failure modes, because they are not all the same problem.

Shared Hotspot Files

Every JavaScript or TypeScript project has a small set of files that every agent wants to touch: package.json, tsconfig.json, vite.config.ts, .env.example. These files are configuration roots — changes to them cascade across the entire project. When two agents modify package.json concurrently, you do not get a clean three-way merge. You get a conflict that requires a human to reason about dependency versions, script definitions, and peer requirements simultaneously. That is not a merge problem. That is a coordination problem that was never surfaced before the damage was done.

Race Conditions on Shared State

Beyond config files, agents running in the same working directory share the filesystem, the local database (if you are running migrations), and the dev server port. Agent A starts a migration. Agent B reads the schema before the migration commits. Agent B generates code against a schema that no longer exists by the time it tries to run tests. The failure is silent until CI catches it — or until it does not.

Context Drift

AI coding agents are stateful within a session but blind across sessions. After fifteen to twenty iterations, an agent's internal model of the codebase drifts from reality. When two agents are drifting in different directions simultaneously, the divergence compounds. By the time you try to merge, you are reconciling not just code changes but two incompatible mental models of what the code is supposed to do.

Git Worktrees 101: The Isolation Primitive

Git worktrees are the underused feature that makes parallel agent workflows tractable. A worktree lets you check out multiple branches from the same repository simultaneously, each in its own directory, without cloning the repo. They share the same .git object store, so they are cheap to create and fast to switch between — but each worktree has its own working directory, its own index, and its own HEAD.

# Create three isolated worktrees from your main branch
git worktree add ../project-refactor feature/refactor-auth
git worktree add ../project-tests feature/add-unit-tests
git worktree add ../project-docs feature/update-docs

Now you have three directories, each on its own branch, each completely isolated from the others. An agent working in ../project-refactor cannot touch files in ../project-tests. There is no shared working directory to race on.

The Three-Layer Isolation Stack

Worktrees handle filesystem isolation, but a production-grade parallel agent setup needs two more layers:

Layer 1 — Worktree (filesystem isolation). Each agent gets its own branch and directory. Config hotspot files like package.json and tsconfig.json are isolated per worktree. Agents cannot overwrite each other's changes.

Layer 2 — Database branch (state isolation). If your project uses a local database, give each worktree its own database or schema. Tools like Neon and PlanetScale support branching at the database layer. For local Postgres, a simple naming convention (project_refactor_dev, project_tests_dev) is enough. Set the DATABASE_URL environment variable per worktree so agents never share migration state.

Layer 3 — Port assignment (network isolation). Assign each worktree a distinct dev server port. project-refactor runs on 3001, project-tests on 3002, project-docs on 3003. Add a .env.local to each worktree directory with the correct PORT value. Agents that spin up dev servers will no longer fight over port 3000.

With all three layers in place, each agent operates in a hermetically sealed environment. The only shared resource is the Git object store — and that is exactly what you want, because it is the integration point you control.

Assigning Agents to Worktrees: Which Runtime for Which Task

Not all agents are equal, and the worktree pattern works best when you match agent strengths to task types.

Claude Code → complex refactors. Claude Code's strength is multi-file reasoning with high coherence across a large context window. Assign it to the refactor worktree for tasks like extracting a service layer, migrating from one auth pattern to another, or restructuring a module boundary. These tasks require understanding how changes in one file ripple through ten others — exactly what Claude Code handles well.

Codex → test generation. Codex is fast, precise, and well-calibrated for generating unit and integration tests against an existing implementation. Assign it to the tests worktree with a clear prompt: the files to cover, the testing framework in use, and the coverage threshold to hit. Codex does not need to understand the whole codebase — it needs to understand the interface it is testing.

Gemini CLI → large-context documentation. Gemini's extended context window makes it the right tool for documentation tasks that require holding the entire codebase in view: API reference generation, architecture decision records, onboarding guides. Assign it to the docs worktree and point it at the source tree. It will produce documentation that reflects the actual code rather than a stale summary.

This division of labor is not arbitrary. It means each agent is operating at its ceiling, and the outputs are complementary rather than overlapping. The refactor branch changes the implementation. The tests branch validates it. The docs branch describes it. When you merge in that order, each layer builds on the previous one.

The Orchestration Layer: How Medley.sh Manages Parallel Missions

The worktree setup solves isolation. It does not solve coordination. You still need to know which agent is working on what, whether any of them are blocked, and in what order to merge their outputs. Without an orchestration layer, you are back to babysitting terminals — just in three separate directories instead of one.

This is the problem Medley.sh is built to solve. Medley.sh is a macOS-native orchestration app that routes coding missions across Claude Code, Codex, Gemini, Cursor, and Kimi from a single Attention Queue. Instead of opening three terminal tabs and manually tracking agent progress, you define missions in Medley.sh and let the queue manage dispatch, status, and sequencing.

The Attention Queue gives you a single pane of glass across all running agents. You can see at a glance which missions are active, which are blocked waiting for a dependency, and which have completed and are ready to merge. When an agent surfaces a blocker — a file it cannot resolve, a test that is failing, a schema mismatch — it appears in the queue as an item requiring your attention, not as a silent failure buried in a terminal scroll buffer.

Because Medley.sh runs locally on your Mac, your code never leaves your machine. There is no cloud intermediary routing your source files through a third-party service. The orchestration layer is local-first by design, which matters when you are working on proprietary codebases or pre-release features.

Medley.sh also tracks cost per task. Each mission in the queue shows you what it cost to run, so you can make informed decisions about which agent to use for which task rather than discovering a surprise bill at the end of the month.

Sequential Merging and Quality Gates

Parallel execution, sequential integration. This is the rule that keeps the workflow clean.

When all three agents complete their missions, do not merge everything at once. Merge in dependency order with a quality gate between each step:

Merge the refactor branch first. Run your full test suite against it. If tests pass, merge to main. If they fail, the refactor branch is the problem — fix it in isolation before touching anything else.
Rebase the tests branch onto the updated main. The tests branch was generated against the pre-refactor implementation. After rebasing, run the tests. Some will need minor updates to match the refactored interfaces — this is expected and scoped. Merge when green.
Rebase the docs branch onto the updated main. Documentation generated against the pre-refactor code will have stale references. A second Gemini CLI pass over the diff is usually enough to update them. Merge when accurate.

This sequence means that at every merge point, you have a passing test suite and a clean main branch. There is no moment where you are holding three sets of conflicting changes and trying to reconcile them simultaneously.

Common Failure Modes and How to Recover

Stale file locks. Some tools write lock files (yarn.lock, package-lock.json) that can conflict even across worktrees if you run install commands in multiple directories simultaneously. Stagger your dependency installs or use a shared node_modules symlink pattern if your package manager supports it.

Zombie processes. An agent that crashes mid-task can leave a dev server or watcher process running on its assigned port. Before starting a new mission in a worktree, run lsof -i :<port> to confirm the port is free. Medley.sh surfaces process state in the Attention Queue, so you can catch zombie processes before they block the next mission.

Context drift after long sessions. If an agent has been running for more than fifteen to twenty iterations, its internal model of the codebase is likely stale. The fix is to end the session, commit the current state, and start a fresh session with a summary of what has been done. Treat agent sessions like database transactions: short, scoped, and committed frequently.

From Terminal Chaos to a Managed Parallel Pipeline

The pattern described in this guide — worktree isolation, three-layer workspace separation, agent-to-task matching, and orchestrated merging — is not theoretical. It is the workflow that turns a four-hour sequential agent pipeline into a ninety-minute parallel one, without the merge conflicts and miscoordination that make naive parallelism worse than useless.

The Git worktree handles isolation. The three-layer stack handles state. The agent-to-task matching handles quality. And Medley.sh's Attention Queue handles everything else: dispatch, status, blockers, cost tracking, and merge sequencing — from a single interface on your Mac, with your code staying exactly where it belongs.

If you are still managing parallel AI agents across a sprawl of terminal tabs, you are doing the hardest part of the job manually. Try Medley.sh and let the orchestration layer do it for you.