How to Use Multiple AI Coding Agents on One Repo

You’ve picked your AI coding agent. It’s good. But now you’re wondering: what if I ran two? Or three? What if Claude Code handled the hard refactor while Codex CLI wrote the tests and Gemini CLI updated the docs — all at the same time?

The idea is obvious. The execution is where it falls apart.

This guide walks through how to actually run multiple AI coding agents on a single repository — what goes wrong, what works, and how to set up a workflow that scales.

Why Use Multiple Agents?

Different agents have different strengths. Claude Code excels at complex refactors, Codex CLI is fast and cost-effective for everyday tasks, and Gemini CLI is cheap for straightforward work (Google ends its free individual tier on June 18, 2026, with Antigravity CLI as the successor). Using just one means either overpaying for simple tasks or underperforming on hard ones.

But the bigger reason is time. A single agent works sequentially — one task, then the next, then the next. Three agents working in parallel turn an hour of sequential work into twenty minutes of wall-clock time.

The math is simple: if you have five independent tasks that each take ten minutes, one agent takes fifty minutes. Five agents take ten — assuming the tasks don’t touch the same files.

What Goes Wrong When You Try It

Before we get to solutions, let’s be clear about what happens when you naively run multiple agents on the same repo:

Conflict 1: File Collisions

Two agents open the same file, make different edits, and save. The second write silently overwrites the first. You won’t notice until the feature is broken and you can’t figure out why.

Conflict 2: Dirty Working Tree

Agent A makes uncommitted changes. Agent B reads those half-finished changes and treats them as the current state of the code. It builds on top of incomplete work. The result is code that doesn’t make sense to either agent.

Conflict 3: Branch Chaos

Both agents commit to the same branch. The git history becomes an interleaved mess of unrelated changes. Good luck doing a meaningful code review on that.

Conflict 4: Shared State

npm install from one task affects the other. Lock files change mid-task. Build caches become invalid. Type checking reports errors from another agent’s incomplete changes.

These aren’t theoretical. Anyone who’s tried opening two Claude Code sessions in the same directory has hit at least one of them.

The Manual Approach: Git Worktrees

The foundation of any multi-agent workflow is isolation. Each agent needs its own working directory, its own branch, and its own state. Git worktrees provide exactly this.

# Create isolated worktrees for each agent
git worktree add -b feat/auth ../repo-auth
git worktree add -b feat/tests ../repo-tests
git worktree add -b feat/docs ../repo-docs

Each worktree is a separate directory with its own branch, sharing the same git object store. Uncommitted changes in one are invisible to the others — each has its own working directory and staging area.

Now you can start agents in each:

# Terminal 1
cd ../repo-auth && claude

# Terminal 2
cd ../repo-tests && codex

# Terminal 3
cd ../repo-docs && gemini

This works. But managing it is tedious.

The Pain of Manual Management

For each task, you need to:

Create a worktree with a descriptive branch name
Share dependencies across worktrees — symlink or copy node_modules and other gitignored directories so you don’t reinstall per worktree (note: npm install can break symlinked node_modules, so only do this if you won’t install packages in secondary worktrees)
Open a new terminal and cd into the worktree
Start the agent
Monitor it — switch between terminals to check progress
When it’s done, review the diff
Merge the branch back to main
Clean up the worktree

That’s eight steps per task. With five agents running, you’re spending more time managing the workflow than the agents spend coding. And if you forget to symlink node_modules, you’re waiting for a fresh install in each worktree.

A Better Approach: Task-Based Orchestration

What you really want is:

Describe a task
Pick an agent
Everything else happens automatically

The worktree gets created with a clean branch. Dependencies are symlinked. The agent starts in the right directory. You see all agents’ progress at once. When they finish, you review the diff and merge with one action.

This is why I built Parallel Code. It wraps the manual worktree workflow into a task-based interface that handles the plumbing.

Setting Up a Multi-Agent Session

Here’s what a typical session looks like:

Task 1: Complex refactor → Claude Code. It needs deep codebase understanding and will touch many files. Claude Code’s convention-awareness means less review work.

Task 2: Write integration tests → Codex CLI. Straightforward but time-consuming. Codex CLI is fast and reliable for test generation.

Task 3: Update API documentation → Gemini CLI. Mechanical work that doesn’t need deep reasoning. Gemini’s cheapest tier keeps this close to free.

Task 4: Fix CSS layout bug → Gemini CLI. Quick visual task — Gemini handles straightforward layout fixes well, and its low-cost tier keeps costs down.

Task 5: Add error handling to API routes → Codex CLI. Pattern-based work across multiple files. Codex handles this efficiently.

All five start within seconds of each other. Each runs in its own worktree, on its own branch. You watch them work from a tiled dashboard. As each finishes, you review the diff and merge — or discard and retry.

Agent execution time: the duration of the longest task, not the sum of all tasks. You’ll still spend time reviewing and merging each branch, but the expensive part — waiting for agents — is parallelized.

Picking the Right Agent for Each Task

Not every task deserves your most expensive agent. Here’s a practical framework:

Use Claude Code when:

The task requires understanding existing patterns and conventions
Multi-file refactors where consistency matters
Architectural changes that affect many parts of the codebase
Tricky bugs that need deep reasoning to diagnose

Use Codex CLI when:

Feature implementation with clear requirements
Writing tests for existing code
API integrations following documented specs
Medium-complexity tasks where speed matters more than perfection

Use Gemini CLI when:

Documentation updates and generation
Boilerplate code and scaffolding
Simple bug fixes with obvious solutions
Any task where a low-cost tier makes price irrelevant

The key insight: you don’t need the best agent for every task. You need the right agent for each task, running at the same time.

Review Strategy for Multi-Agent Output

Running five agents produces five branches of changes to review. Without a strategy, this becomes overwhelming. Here are the patterns that work:

Review in Difficulty Order

Start with the simplest tasks — docs, boilerplate, simple fixes. These are quick to verify and merge. Getting them out of the way first means fewer branches to track.

Then tackle the complex ones. One caveat: if your simple branches touch files that the complex refactor also modifies, merging them first can create conflicts with the complex branch. In that case, either merge the complex branch first, or rebase it onto main after the simple merges.

Review Diffs, Not Code

Don’t read the full files an agent produced. Read the diff — what changed, and why. A good code review workflow for AI-generated code focuses on the delta, not the whole file.

Discard and Retry Freely

One of the biggest advantages of isolated branches: if an agent’s output isn’t right, discard it. Delete the branch, create a new task, and try again — maybe with a different agent or a more specific prompt. You’ll lose the API cost of the failed run, but the cost of retrying is minutes and a few dollars, not hours of manual rework.

Merge Strategically

Don’t merge everything at once. Merge the independent changes first (docs, tests, isolated features). Then merge the ones that might conflict with each other, resolving conflicts one at a time. This keeps your main branch stable throughout the process.

Common Pitfalls

Running too many agents at once. Start with two or three. Learn the review workflow before scaling to five or ten. The bottleneck shifts from agent execution to your review capacity.

Giving agents overlapping tasks. Two agents editing the same files defeats the purpose of isolation. Split work along file boundaries when possible. If two tasks touch the same code, run them sequentially.

Ignoring cost. Five Claude Code Opus sessions running for an hour can cost $50+. Use the right model tier for each task. Gemini’s low-cost tier exists — use it for work that doesn’t need Claude-level quality.

Skipping the review. Parallel execution makes it tempting to merge faster. Resist. Each branch still needs a proper review. The speed gain comes from parallel execution, not skipped reviews.

Getting Started

If you want to try the manual approach:

Read our git worktrees guide to understand the foundation
Create two worktrees and run two agents on separate tasks
Practice the review-and-merge workflow before adding more agents

If you want the automated approach:

Download the latest Parallel Code release
Open your repo and create a few tasks
Assign agents and watch them work in parallel

Either way, the principle is the same: isolate, parallelize, review, merge. Once you’ve shipped a full afternoon’s work before lunch, you won’t go back to running one agent at a time.