Running Claude Code Agents in Parallel With Git Worktrees

Once one Claude Code session is reliably useful, the obvious next step is running two. One agent builds the feature while another fixes the bug you found while reviewing it. Or three agents try three approaches to the same problem and you keep the best.

Do that in a single checkout and it falls apart within minutes. Both agents edit the same files, switch the same branch, and run tests against each other's half-finished changes. You end up debugging the collision instead of the code.

The standard fix is git worktrees. Here's how they work, how to use them with Claude Code, and the problems they don't solve.

What a worktree is

A normal clone has one working directory: one set of files, one checked-out branch. A worktree is an additional working directory attached to the same repository. Each worktree has its own files and its own branch, but they all share one .git history and one set of remotes.

git worktree add ../myapp-auth -b feature/auth
git worktree add ../myapp-bugfix fix/issue-412
git worktree list

Now ../myapp-auth and ../myapp-bugfix are full checkouts on different branches. Commits made in either are immediately visible to the other, because it's one repository. No second clone, no syncing.

Using them with Claude Code

You can create worktrees yourself as above and run claude inside each. Claude Code also has built-in support: start it with --worktree (or -w) and a name, and it creates an isolated worktree for you.

claude --worktree feature-auth
claude --worktree fix-412      # in a second terminal

By default these go under .claude/worktrees/<name>/ at the repository root, each on its own new branch. Add .claude/worktrees/ to your .gitignore so they don't show up as untracked files in your main checkout. When you exit a session, Claude Code checks for uncommitted work before offering to remove the worktree.

You can also branch a worktree straight from a pull request with claude --worktree "#1234", which is handy for "go address the review comments on this PR" while you keep working on something else.

The four problems worktrees don't solve

Worktrees isolate files. That's all. Everything else your project touches is still shared, and that's where parallel agents actually collide.

1. Gitignored files aren't there

A worktree is a fresh checkout, so anything gitignored — .env, .env.local, local config — doesn't exist in it. The agent starts, the app can't find its configuration, and it either fails or (worse) invents values.

Claude Code handles this with a .worktreeinclude file at your project root, using .gitignore syntax. Matching gitignored files are copied into each new worktree:

.env
.env.local

2. Dependencies need installing per worktree

node_modules, virtualenvs, and build caches are per directory. Each new worktree starts without them, so the first thing every agent does is a full install. For a large project that's minutes and gigabytes per worktree. Package managers with a shared content store (pnpm, uv) make this much cheaper, which is a good reason to use them if you run agents in parallel.

3. Ports collide

Two worktrees running npm run dev both try to bind port 3000. The second one fails — or the agent "fixes" it by killing whatever is on port 3000, which is the other agent's server.

Make the port configurable from the environment and give each worktree its own:

# .env in each worktree
PORT=3001

Put a line in CLAUDE.md saying so, or an agent will eventually reach for kill.

4. The database is shared

This is the one that bites hardest. Both worktrees read the same DATABASE_URL, so both agents run migrations, seed data, and truncate tables in the same database. Agent A's test suite wipes the fixtures agent B was relying on, and B spends twenty minutes debugging a failure that doesn't exist in its code.

The fix is a database per worktree: a separate database name on the same server at minimum, a separate instance ideally.

createdb myapp_auth
createdb myapp_bugfix
# then point each worktree's .env at its own

A setup that works

Putting it together:

Add .claude/worktrees/ to .gitignore.
Add a .worktreeinclude listing your env files.
Make ports and DATABASE_URL come from environment variables, with nothing hardcoded.
Give each worktree its own port and database.
Put the rules in CLAUDE.md: which port range agents may use, never kill processes they didn't start, never touch another worktree's database. (See How to Write a CLAUDE.md.)
Have each agent finish by pushing its branch and opening a pull request, so merging is something you do deliberately and not something that happens by accident.

How many agents is too many

The limit is rarely the machine. It's you.

Every parallel agent produces work that needs reviewing, and review is the bottleneck. Two or three well-scoped agents on independent tasks is a big productivity win. Six agents on overlapping parts of the codebase produces six pull requests that conflict with each other and one very long afternoon.

Parallelism works best when tasks touch different files, have clear definitions of done, and can be reviewed independently. If you can't describe the task in a paragraph, it probably shouldn't be running unattended alongside three others.

When worktrees stop being enough

Worktrees are the right tool on one machine. Their limits all come from sharing one host: one set of ports, one database server, one pool of memory, one disk. When a build in one worktree eats all the RAM, the others slow down or crash.

The next step up is giving each parallel line of work its own isolated environment — its own container, its own database, its own URL — so that isolation covers everything the agent touches, not just its files. That's more infrastructure, but it's the only version where "run it in parallel" doesn't come with an asterisk.

EasySpawn gives each workspace its own isolated container, its own managed database, and a live URL per branch — so parallel agents don't share ports, data, or memory. See how it works or join the waitlist.