How to use Git worktrees to run multiple Claude Code and Cursor agents in parallel without branch collisions

A practical guide to creating isolated working trees for parallel AI-assisted development, merging results cleanly, and avoiding stale branch metadata.

TL;DR: Git worktrees let you check out multiple branches into separate directories from the same repository. Each directory gets its own HEAD and working files while sharing one `.git` database. Launch Claude Code or Cursor in each directory to run agents simultaneously without file collisions or branch checkout conflicts.

TL;DR: Git worktrees let you check out multiple branches into separate directories from the same repository. Each directory gets its own HEAD and working files while sharing one .git database. Launch Claude Code or Cursor in each directory to run agents simultaneously without file collisions or branch checkout conflicts.

The Problem: Why Agents Collide in a Single Working Tree

Running multiple Claude Code or Cursor sessions in the same repository fails because every agent shares a single working tree, one HEAD, and the same untracked files on disk. When two agents modify the same paths simultaneously, the filesystem becomes the bottleneck and the git index gets corrupted.

Imagine Agent A scaffolds a payment module while Agent B edits the same file. Because both processes see the identical directory:

# Agent A writes its implementation
echo "class PaymentGateway:" > payments/gateway.py

# Agent B concurrently overwrites with different logic
echo "class StripeClient:" > payments/gateway.py

Only the last write survives; the first agent’s partial edit is silently lost. The shared HEAD compounds the collision. If Agent A stages work:

git add src/auth.ts

Agent B immediately sees that staged hunk in its own git status. If Agent B then discards changes to reset its context:

git checkout -- .

It wipes Agent A’s staged edits along with its own. Untracked files—build artifacts, generated logs, or temporary configs—are equally global, so one agent’s noise pollutes every other session’s working tree and git state. Merge conflicts can appear in the index before either agent has finished, git diff becomes unreadable, and commit messages may accidentally include another agent’s changes. Because the filesystem and index are singular for the directory, agents race each other instead of running in parallel. True concurrent development is impossible while every session competes for the same working tree.

Create a Worktree for Each Agent

Create a separate worktree for each agent from your main project directory so every feature branch gets its own isolated working directory while still sharing a single .git object database. This is the foundation for running multiple Claude Code or Cursor instances in parallel without branch collisions.

Run the following from your main project directory to create linked working trees for two parallel agents on fresh branches:

git worktree add .worktrees/feature-a -b feature-a
git worktree add .worktrees/feature-b -b feature-b

These commands create .worktrees/feature-a and .worktrees/feature-b as peer directories to your main working tree, each checked out to its own branch. Every worktree maintains its own HEAD, index, and tracked files, yet all of them reference the same underlying .git object database. Consequently, a git fetch or git pull in any worktree updates the shared refs for every tree instantly, and commits authored in one directory are immediately reachable from the others without pushing or re-cloning.

Because each agent operates inside its own working tree, they cannot overwrite each other’s uncommitted changes or interfere with each other’s file state. You can open one Claude Code session in .worktrees/feature-a and a second in .worktrees/feature-b; edits to src/App.tsx in one tree leave the other tree’s copy untouched, which eliminates the risk of cross-agent file collisions entirely. Repeat the git worktree add pattern for each additional agent, keeping every branch in its own folder under .worktrees/.

Launch Agents in Parallel

Open a terminal pane for each worktree and start your AI assistant from that directory so every agent runs in its own branch context without checkout conflicts. Each process sees only the files inside its assigned directory, which means you can assign independent tasks—such as bug fixes, feature builds, or refactors—without overlapping edits. This pattern works for Claude Code, Cursor, or any other agent that respects the current working directory and reads files relative to its launch point.

# Pane 1
cd .worktrees/feature-a && claude
# Pane 2
cd .worktrees/feature-b && claude

As noted above, each instance sees only its own directory’s files, so agents run independently without branch checkout conflicts. You can scale this across three, four, or more panes by matching each to its own worktree path. Use a terminal multiplexer or your IDE’s split-terminal view to keep every session visible at once. Before launching, verify the pane is on the intended branch:

git branch --show-current

Because the branches are already checked out in their respective directories, the agents never need to switch branches and risk collision. Monitor output in each pane separately to track parallel progress, and issue commands to each agent knowing its scope is strictly limited to its isolated working tree.

Merge Finished Work and Remove Worktrees

When an agent finishes its task, merge its branch from your main project directory and then remove the worktree using Git’s native command. This keeps your repository clean and prevents stale references from accumulating, ensuring the shared object database remains in a consistent state.

Begin the integration by checking out your main branch and merging the agent’s feature branch:

git checkout main
git merge feature-a

Review the diff, run your test suite, and resolve any merge conflicts that surface. Once the merge commit is finalized and the feature is fully integrated, delete the isolated working directory with Git’s built-in removal command:

git worktree remove .worktrees/feature-a

This deletes the directory and simultaneously clears the internal metadata Git maintains for active worktrees, so no manual cleanup is required. Repeat this merge-and-remove cycle for each agent branch as its workstream completes. If you ever delete a worktree directory manually—using rm or a file manager—you must run the prune command afterward:

git worktree prune

Omitting git worktree prune leaves stale entries inside .git/worktrees/, which causes Git to treat the branch as still checked out. That phantom checked-out state blocks branch deletion with git branch -d and can produce warnings during future worktree operations until the references are explicitly cleared.

Isolate Databases and Ports

Assign each worktree its own environment variables for database names and server ports so parallel agents do not interfere at runtime. File isolation from separate working directories prevents branch collisions, but runtime state—databases, caches, and development servers—can still clash if every agent targets the same resources.

Without this separation, two agents competing for the same local database or HTTP port will crash with EADDRINUSE errors or silently corrupt each other’s data. Even separate databases on the same server instance require distinct names or connection strings to avoid one agent dropping tables another just created. The simplest fix is to export distinct values in the shell before launching each Claude Code instance:

# Terminal for feature-a
cd .worktrees/feature-a
export DATABASE_URL=postgres://localhost/project_a
export PORT=3001
claude
# Terminal for feature-b
cd .worktrees/feature-b
export DATABASE_URL=postgres://localhost/project_b
export PORT=3002
claude

If your application reads from a .env file, create a worktree-specific override that is ignored by Git:

# Inside .worktrees/feature-a/
echo "DATABASE_URL=postgres://localhost/project_a" >> .env.local
echo "PORT=3001" >> .env.local

Add .env.local to your global .gitignore so it remains untracked and does not leak across worktrees. Frameworks that automatically load .env.local will pick up these overrides without code changes. You can apply the same pattern to cache directories, build output folders, or temporary file paths by exporting additional worktree-specific variables. With these boundaries in place, agents can boot development servers, run database migrations, and execute integration tests simultaneously without runtime collisions.

FAQ

Do worktrees duplicate the repository history?

No. All worktrees share a single .git object database, so clones, fetches, and commits stay synchronized without duplicating history.

Can I run Cursor and Claude Code in worktrees at the same time?

Yes. Any tool that operates on a working directory can run independently in its own worktree because each has separate tracked files and HEAD.

Why can't I just use git checkout -b in separate folders?

Standard git checkouts in the same repository compete for the single working tree. Worktrees are the native Git mechanism for multiple checked-out branches.

What happens if I delete a worktree folder manually?

Git retains metadata that the branch is still checked out. Run git worktree prune to clear stale references so the branch can be deleted or moved normally.

How many parallel agents can I run?

Workflows commonly run three, four, or five Claude Code sessions simultaneously. The practical limit depends on your machine's resources and the number of branches you create.

References for further reading

_Sources consulted while researching this guide, included so you can verify the details and go deeper. Listing them is not a claim that every line was independently fact-checked._

I packaged the setup above into a ready-to-use kit — Parallel Agent Orchestration Playbook: 16 Patterns for Concurrent Agents — for anyone who'd rather copy-paste than wire it from scratch: https://unfairhq.gumroad.com/l/ijggu.

Last updated: 2026-07-01

Related guides