DEV Community

Christopher Hoeben
Christopher Hoeben

Posted on • Originally published at stickwithfiddle-sys.github.io

How to Use Git Worktrees to Run Claude Code and Cursor Agents in Parallel Without Branch Collisions

#gitworktrees #claudecode #cursor #paralleldevelopment

How to Use Git Worktrees to Run Claude Code and Cursor Agents in Parallel Without Branch Collisions

A practical playbook for isolating multiple AI coding agents in separate directory checkouts so they never overwrite each other’s work.

TL;DR: Git worktrees let you check out multiple branches from the same repository into separate directories, giving each AI agent its own isolated workspace. Pair that with database branching and port isolation, and you can run several Claude Code or Cursor sessions simultaneously on independent tasks without file collisions or context pollution.

Why Sequential Agent Workflows Hit a Wall

Running AI agents sequentially on a single branch creates a hard throughput ceiling: one agent, one terminal, one branch, and one task at a time is the maximum concurrency the setup allows. When multiple sessions share the same working directory, they collide on filesystem state—one agent rewrites a file while another is mid-edit, tests fail for reasons that have nothing to do with the feature being built, and context windows fill up with noise from other agents’ work.

The collision surface is broad because every session competes for the same Git working tree. If two Claude Code agents target the same repository, one can overwrite files the other is editing, leaving the index in an inconsistent state. Tests fail for reasons that have nothing to do with the feature being built because the database is in an unexpected state. Context windows fill up with noise from other agents’ work, forcing each session to process irrelevant diffs and wasting tokens on unrelated changes.

The root cause is the shared working directory. Most teams trying parallel AI development without isolation hit file conflicts immediately. Switching branches manually to multiplex tasks destroys context and forces sequential idle time, since you can only check out one branch at a time in a single directory.

Parallel agentic development fixes this by isolating each agent in its own working directory, typically through git worktrees, so they can work on separate features simultaneously without stepping on each other. For example, you can spin up dedicated checkouts for an auth refactor, a new chat feature, and a bug fix, then run a Claude Code session in each:

git worktree add ../project-auth refactor-auth
git worktree add ../project-chat feature-chat
git worktree add ../project-fix hotfix-login
Enter fullscreen mode Exit fullscreen mode

Each directory is an independent checkout backed by the same repository, eliminating the single-branch queue and letting agents run in parallel.

What Git Worktrees Actually Are

Git worktrees are a native Git feature that lets you check out multiple branches from the same repository into separate directories simultaneously, all sharing a single .git folder. This gives each branch its own isolated working tree without requiring multiple clones of the repo.

In a standard repository, a branch is only a pointer to commit history, and you can only have one branch checked out at a time in a given directory. Switching branches rewrites the working tree in place, which forces sequential work. Git worktrees remove that bottleneck by letting you check out multiple branches from the same repo simultaneously, each in its own directory, all sharing the same .git directory. That architecture gives each agent an isolated working directory while the repository itself remains singular, so file changes in one tree never collide with another.

To create a worktree for a new feature branch:

git worktree add ../my-project-auth auth-refactor
Enter fullscreen mode Exit fullscreen mode

This checks out the auth-refactor branch into ../my-project-auth. To see all linked worktrees:

git worktree list
Enter fullscreen mode Exit fullscreen mode

When a worktree is no longer needed, remove it cleanly:

git worktree remove ../my-project-auth
Enter fullscreen mode Exit fullscreen mode

Because every worktree references the same underlying object database, commits created in one directory are instantly visible to the others, yet working directory changes and untracked files stay completely separate. That separation is the exact mechanism that lets multiple AI agents run in parallel on independent tasks without stepping on each other or creating merge conflicts in the working tree.

Setting Up Worktrees for Parallel Agents

Create a dedicated worktree for each agent from your main repository, checking out a unique branch in its own directory so agents operate in complete isolation. This prevents file collisions and uncommitted change conflicts while letting Claude Code or Cursor run simultaneously against the same codebase.

A common approach is to create a separate directory for each agent task. For example, you might spin up distinct environments for a major authentication refactor, a new AI chat feature, and a high-priority bug fix. Each worktree checks out its own branch, so agents never collide over file locks or uncommitted changes. Keep worktree paths predictable—such as a root project folder with subdirectories named for each branch—so your terminal and editor sessions stay organized.

From your main repository, add a new worktree linked to an existing branch:

git worktree add ../myproject-auth-refactor auth-refactor
Enter fullscreen mode Exit fullscreen mode

To create and check out a new branch in one step:

git worktree add -b feature/ai-chat ../myproject-ai-chat
Enter fullscreen mode Exit fullscreen mode

Because each worktree is an isolated working directory checked out from the same repository, one agent’s changes never interfere with another’s session. Confirm active worktrees and their paths with:

git worktree list
Enter fullscreen mode Exit fullscreen mode

When the task is complete, remove the directory and prune the worktree entry:

git worktree remove ../myproject-auth-refactor
Enter fullscreen mode Exit fullscreen mode

This structure keeps every agent’s edits, build artifacts, and dependencies fully separate while all worktrees share the same underlying Git history.

Isolating Databases and Ports

Pair each git worktree with its own database schema and dedicated local ports so that every agent operates against an isolated data state and non-conflicting service endpoints. This prevents schema collisions and test failures when multiple agents run migrations or start development servers in parallel.

Filesystem isolation alone is not always enough. When two agents share a single database, a migration run by one agent can invalidate the assumptions of a test suite running in another worktree. Without separate data layers, one agent’s schema migration or seed data can silently break another agent’s test suite. A common pattern is to map each worktree to a separate database instance or schema, and to assign unique ports to any local servers the agents start. For PostgreSQL, direct each worktree to a distinct schema via its connection string:

# worktree-a
export DATABASE_URL=\"postgresql://localhost:5432/app?search_path=agent_a\"
# worktree-b
export DATABASE_URL=\"postgresql://localhost:5432/app?search_path=agent_b\"
Enter fullscreen mode Exit fullscreen mode

If your stack spins up a local web server, hardcode a unique port per worktree so agents do not compete for the same socket:

# worktree-a/.env
PORT=3001
# worktree-b/.env
PORT=3002
Enter fullscreen mode Exit fullscreen mode

You can also inject these values through a shell wrapper that enters the worktree, exports the correct variables, and then launches Claude Code. Keeping data and endpoints isolated ensures that tests, seeds, and hot-reload servers in one tree never interfere with another, which makes parallel agentic development reliable.

Running Agents and Merging Back Cleanly

Launch each Claude Code or Cursor session from a dedicated worktree directory so every agent works on its own branch, then merge the branches back to main when the tasks finish. Because each agent operates in isolation, you avoid file collisions and keep the git history clean.

Create a worktree for each independent task. For example, if one agent refactors authentication while another builds a chat feature, check out separate branches in sibling directories:

git worktree add ../myapp-auth refactor-auth
git worktree add ../myapp-chat feature-chat
Enter fullscreen mode Exit fullscreen mode

Start the agent inside a single worktree and restrict it to that directory. Let each session operate exclusively inside its own folder so it cannot see or touch another agent’s uncommitted changes:

cd ../myapp-auth
claude
Enter fullscreen mode Exit fullscreen mode

When the agents finish, merge everything back cleanly because each unit of work already lives on its own isolated branch. From the main repository, pull the latest main and merge the agent branches in order:

git checkout main
git pull origin main
git merge refactor-auth
git merge feature-chat
Enter fullscreen mode Exit fullscreen mode

After a successful merge, remove the worktree directories to keep the filesystem tidy:

git worktree remove ../myapp-auth
git worktree remove ../myapp-chat
Enter fullscreen mode Exit fullscreen mode

If a branch was created directly inside the worktree and is no longer needed, delete it after merging to prevent stale branches. Because the agents never shared a working directory, you sidestep the spurious conflicts that happen when multiple agents edit the same checkout simultaneously. Should a conflict arise during merge, resolve it in the main repository while the agent’s original branch remains untouched in its worktree.

FAQ

How many parallel agents can I realistically run?

Teams commonly run three, four, or five Claude Code sessions simultaneously, though your practical limit depends on available CPU, memory, and how well you have isolated databases and ports.

Do worktrees duplicate the entire repository on disk?

No. Worktrees share the same .git object database and history; only the working directory files are duplicated per branch.

How do I prevent database conflicts between agents?

You should pair git worktrees with database branching and port isolation so each agent has its own data state and service endpoints. A common pattern is to assign a separate database schema or containerized instance to each worktree.

Can I use worktrees with Cursor or other AI editors?

The playbook is built around Claude Code, but the pattern applies to any agentic tool that operates on a filesystem checkout. As long as the tool points to a distinct worktree directory, it will remain isolated from other sessions.

What is the best way to merge completed agent work?

Each worktree operates on its own branch, so you can merge everything back cleanly into your main branch when the tasks are done.

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.*

Top comments (0)