Run a Team of AI Agents in Parallel with Git Worktrees

Problem: You point a second AI coding agent at the same repo as the first, and within ten minutes they are both editing src/auth.ts. One overwrites the other mid-change. You get half-applied diffs, a broken build, and no idea which agent did what.

Quick Win: Give each agent its own checkout before you start it.

git worktree add ../app-feature-auth -b feature-auth

That command creates a second working directory next to your repo, on its own branch, sharing the same .git history. Run it again with a different name and you have two isolated workspaces. Start one agent in each, and neither can touch the other's files. This page is about doing that on purpose, across a whole team of agents, without it turning into chaos.

What is a git worktree?

A git worktree is a second working directory tied to the same repository, checked out on its own branch. You get the files, the branch, and the index of a separate clone, but all the worktrees share one .git object database, so there is no duplicate history and no extra remote to manage.

The command has existed in git since 2015. What changed in 2026 is the reason people reach for it. It stopped being a niche trick for hotfixes and became the standard way to run more than one AI agent against a single codebase. The Nx team (August 7, 2025) was early to frame it this way: hand a branch to an agent in its own worktree, then switch back to your editor and keep working while the agent runs in the background.

The three commands you will use constantly:

git worktree add ../app-feature-auth -b feature-auth
git worktree list
git worktree remove ../app-feature-auth

The first creates a worktree at ../app-feature-auth on a new branch feature-auth. The second prints every worktree and the branch it sits on. The third tears one down when you are done.

Why run AI agents in separate worktrees?

Because isolation beats coordination. If two agents share one working directory, you have to make them coordinate every file write, and they are bad at it. If each agent has its own worktree, they never need to coordinate at all, because they physically cannot touch the same files.

The Claude Code worktree docs put the boundary plainly: edits in one session never touch files in another, so you can have Claude building a feature in one terminal while fixing a bug in a second. The agents have no awareness of each other, and that is the point.

File collisions are only the first failure mode. Two agents sharing one dev database produce interleaved state that makes neither feature testable. Two agents binding the same port crash on startup. So a real worktree workflow isolates three things, not one:

• Files come for free with the worktree.
• The database needs a separate branch or a separate local instance per agent.
• The dev server port needs to differ per worktree.

Here is a setup script that creates a worktree, copies your local env file in, assigns a unique port, and installs dependencies. A fresh worktree is a clean checkout, so gitignored files like .env are not there until you copy them.

#!/usr/bin/env bash
# new-agent.sh <branch-name> <port>
set -euo pipefail

BRANCH="$1"
PORT="$2"
ROOT="$(git rev-parse --show-toplevel)"
DIR="../$(basename "$ROOT")-${BRANCH}"

git worktree add "$DIR" -b "$BRANCH"
cp "$ROOT/.env.local" "$DIR/.env.local"
echo "PORT=${PORT}" >> "$DIR/.env.local"
(cd "$DIR" && npm install)

echo "Worktree ready at $DIR on port $PORT"

Run it three times and you have three agent-ready workspaces, each on its own port, each with its own env, none of them fighting.

How to set up parallel agents step by step

The workflow is: create one worktree per task, start one agent per worktree, let them run, then review and merge. Five steps.

First, decide the tasks. Parallel agents work when the tasks are independent. "Add the billing page," "write API tests," and "fix the dark-mode bug" can run side by side. "Refactor the auth model" and "build a feature that depends on the auth model" cannot, so sequence those.

Second, create a worktree per task. Use the script above, or run the raw command for each one:

git worktree add ../app-billing -b billing
git worktree add ../app-api-tests -b api-tests
git worktree add ../app-darkmode-fix -b darkmode-fix

Third, start one agent in each worktree. With Claude Code you can do this two ways. The manual way is one terminal per worktree:

cd ../app-billing && claude

The built-in way skips the manual git worktree add. Passing --worktree to Claude Code creates the isolated worktree for you under .claude/worktrees/ and starts the session in it:

claude --worktree billing

If you copy local config into worktrees often, add a .worktreeinclude file to your project root. It uses gitignore syntax, and Claude Code copies any matching gitignored file into every new worktree it creates:

.env
.env.local
config/secrets.json

Fourth, let them run and keep an eye on them. This is where a manager beats a wall of terminals, which the next section covers.

Fifth, review and merge each branch back. That is its own section too, because it is where most of the real work moves once your agents are fast.

How many agents can you actually run?

Five to seven on a modern laptop. After that, rate limits, disk usage, and the time it takes you to review the output cancel out the speed you gained.

The Agentic Blog's worktree writeup (March 31, 2026) puts the productive ceiling at 5-7 concurrent agents before those three costs eat the throughput gains. The disk cost is the one people underestimate. Each worktree is a full checkout of your tree plus its own node_modules, so six of them on a mid-size project can be 30 GB or more. The same writeup cites a Cursor report of automatic worktree creation consuming 9.82 GB in a single 20-minute session.

The tooling agrees. Superset, which launched as Product Hunt's #1 Product of the Day on February 27, 2026 and bills itself as running 10-plus parallel agents, currently orchestrates somewhere between five and seven agents in practice, with 100 as a stated end-of-2026 goal (popularaitools.ai review). The marketing number and the working number are not the same.

The harder limit is you. Six agents finishing at once means six diffs to review and six branches to merge. That review queue is the real bottleneck, and it does not parallelize. Start with two or three, get the merge habit down, then scale up.

What tools manage parallel agents for you?

You do not have to run all of this from raw terminals. A category of GUI managers grew up around exactly this workflow in early 2026, each one mapping one worktree to one agent (Nimbalyst tool roundup, April 23, 2026):

• Superset is a desktop IDE that runs 10-plus agents in a unified dashboard, one worktree per agent, supporting Claude Code, Codex, Cursor Agent, Gemini CLI, and others.
• Vibe Kanban (open source, originally from BloopAI) is a kanban board where a card equals a worktree equals an agent. It supports 10-plus CLI agents.
• Conductor (Melty Labs) is a diff-first dashboard with one worktree per agent.
• Nimbalyst is a visual workspace where each session can spawn its own worktree, with a session kanban, diff review, and a merge GUI built in.

IDEs caught up too. IntelliJ IDEA 2026.1 (March 27, 2026) shipped first-class git worktree support, framed around exactly this use: "Work in parallel branches and hand one off to an agent while you keep moving in another."

Pick a manager when watching three terminals stops scaling. The underlying mechanism is the same git worktree either way, so you can start raw and graduate to a GUI without changing how your repo works.

Merging the work back together

Merge in dependency order, one branch at a time, building and testing after each merge. Resist the urge to merge all six branches at once, because if the build breaks you will not know which branch did it.

The basic loop, run from your main checkout:

git checkout main
git merge billing
npm run build && npm test
git merge api-tests
npm run build && npm test
git merge darkmode-fix
npm run build && npm test

The Agentic Blog writeup describes two patterns for who does the merging. The lead-agent pattern has one orchestrator agent review and merge the others' output, resolving conflicts in dependency order. The human review gate has you review each branch before it merges, which is slower but safer for anything critical.

One coordination artifact makes both patterns smoother: a top-level AGENTS.md (or CLAUDE.md) that declares which files each agent owns, which directories are off limits, and the build and test commands. When agents respect declared ownership, their branches touch different files and merge cleanly with no conflicts to resolve.

Once a branch is merged, clean up its worktree so it stops eating disk and showing up in git worktree list:

git worktree remove ../app-billing
git branch -d billing

This is also where an orchestrator earns its keep. Running eight terminals by hand means you are the orchestrator: you assign tasks, watch progress, and sequence the merges. Build This Now inverts that. Its orchestrator triages each task, decides how many agents the work needs and in what order, runs them in isolated worktrees, and runs every branch through type-check, lint, and build gates before it merges, so you review finished work instead of refereeing it.

Final file tree

After running three agents in parallel from a repo named app, your filesystem looks like this. The worktrees sit as siblings of the main checkout, each on its own branch, all sharing the one .git in the original directory:

workspace/
├── app/                      # main checkout, branch: main
│   ├── .git/                 # the one shared object database
│   ├── .worktreeinclude      # files to copy into new worktrees
│   ├── AGENTS.md             # file ownership + build/test commands
│   ├── new-agent.sh          # the setup script
│   └── src/
├── app-billing/              # agent 1, branch: billing, PORT 3001
│   ├── .env.local
│   └── src/
├── app-api-tests/            # agent 2, branch: api-tests, PORT 3002
│   ├── .env.local
│   └── src/
└── app-darkmode-fix/         # agent 3, branch: darkmode-fix, PORT 3003
    ├── .env.local
    └── src/

If you use Claude Code's built-in --worktree flag instead of the sibling-directory layout, the worktrees land under app/.claude/worktrees/ rather than next to the repo. Add .claude/worktrees/ to your .gitignore so those folders do not show up as untracked changes in your main checkout.

Frequently asked questions

How many AI agents can I run in parallel at once?

Five to seven on a modern laptop is the practical ceiling, per the Agentic Blog worktree writeup (March 31, 2026). Beyond that, API rate limits, disk consumption (each worktree is a full checkout plus dependencies), and the time it takes you to review the output cancel out the speed gains. Start with two or three.

Do git worktrees use a lot of disk space?

Yes. Each worktree is a full checkout of your working tree plus its own dependency folder like node_modules. Six worktrees on a mid-size project can run 30 GB or more, and a single Cursor session was reported consuming 9.82 GB in 20 minutes. Run git worktree remove on merged worktrees to reclaim the space.

Why not just open multiple terminals in the same folder?

Because every terminal shares one working directory and one branch. Two agents editing the same files at the same time produce half-applied changes and broken builds. Worktrees give each agent its own files, branch, and index, so they physically cannot collide.

Do I need a special tool, or is git enough?

Git alone is enough. The git worktree add, list, and remove commands plus a setup script cover the whole workflow. Tools like Superset, Vibe Kanban, Conductor, and Nimbalyst add a dashboard and merge GUI on top of the same mechanism, which helps once you are running more agents than you can watch in separate terminals.

How do I stop agents sharing the same database and ports?

Worktrees isolate files but not runtime resources. Give each worktree its own database branch or local instance, and assign a unique dev-server port per worktree by writing it into that worktree's .env.local (the setup script above does this). Otherwise two agents will write to the same database or crash trying to bind the same port.

Posted by @speedy_devv