PricingSign inDownload

Blog / claude code

Run multiple Claude Code sessions in parallel without conflicts

Give each session its own git worktree, claim each task first, name one owner for shared files and check merges early. About three at once is plenty.

On this page
  1. Why do parallel Claude Code sessions break each other's work?
  2. Give each session its own git worktree
  3. Do git worktrees prevent merge conflicts?
  4. How do you stop two sessions doing the same task?
  5. How many Claude Code sessions can you run at once?
  6. When this is not enough
  7. Frequently asked questions
  8. Can two Claude Code sessions work in the same folder?
  9. Do git worktrees prevent merge conflicts?
  10. How many Claude Code sessions should I run in parallel?
  11. How do I stop two Claude Code sessions from doing the same task?
  12. Try it with your team

To run several Claude Code sessions on one repository without them breaking each other's work, give each session its own git worktree and branch, have it claim a task before it touches code, and name one owner for the files every feature ends up editing. Worktrees keep the files apart, the claim stops two sessions doing the same job, and an owner for shared files plus an early conflict check keeps merges clean. For most people, about three sessions at once is the useful ceiling, because someone still has to read every diff.

Why do parallel Claude Code sessions break each other's work?#

The first time you run two sessions in one checkout, nothing goes wrong. The trouble shows up later. Session A is halfway through a refactor. Session B runs the test suite, sees a failure caused by A's half-written file, and "fixes" code that was never broken. Then someone runs git add -A, and one commit now holds two unrelated pieces of work and a diff no reviewer can read.

The cause is one shared working directory. Behind that symptom are three separate problems, and each needs its own fix:

ProblemWhat it looks likeWhat stops it
Shared filesOne session tests another's half-finished editA worktree per session
Duplicate workTwo sessions fix the same bug two different waysA claim before work starts
Merge conflictsLockfiles and route tables collide at review timeOne owner for shared files, and a check before merge

Give each session its own git worktree#

A git worktree is a second working directory backed by the same repository. Each one has its own branch and its own files on disk, so a half-finished edit in one is invisible to the other.

bash
git fetch origin
git worktree add ../shop-auth -b feat/auth origin/main
git worktree add ../shop-search -b feat/search origin/main
cd ../shop-auth && claude

Claude Code can do this for you. claude --worktree auth creates .claude/worktrees/auth on a branch named worktree-auth, and claude --worktree with no name picks one. The worktree docs cover cleanup.

Three things bite people on day one.

Untracked files don't come along. A fresh worktree has no .env and no local config. Claude Code reads a .worktreeinclude file at the repo root, a list of gitignored files to copy into each new worktree:

.env
.env.local
config/secrets.json

Ports and databases are still shared. Two dev servers both want port 3000, and two sessions migrating one local database corrupt each other as surely as two sessions editing one file. Give each worktree its own PORT and database name.

Git refuses a branch checked out twice. That is a feature. git worktree list shows which worktree has it. When a branch lands, git worktree remove ../shop-auth cleans up.

Do git worktrees prevent merge conflicts?#

No. They postpone them. Isolation moves the collision from edit time to merge time.

There is a quieter kind too. Session A changes what a function returns; session B writes new code that relies on the old behaviour. Both branches pass their tests, git merges them cleanly, and the result is broken. A May 2026 paper on arXiv describes the same pattern: isolating agents hides conflicts of meaning until the branches meet. How to stop two AI coding agents editing the same files covers the checks that catch them.

The files that conflict line by line are predictable: lockfiles, migrations, the file that registers every route, any index.ts that re-exports things, and generated code. Decide who owns them before the sessions start, and write it where every session will read it. In CLAUDE.md:

md
## Parallel work
- You are working in a git worktree. Never edit files outside it.
- Stay in the directories named in your task. If you need a change elsewhere, stop and say so.
- Do not touch `package-lock.json`, `db/migrations/`, or `src/routes/index.ts`.
  Ask the owner of shared files to make the change.
- Commit small and often. Never use `git add -A`; add the files you changed.
- Rebase on `origin/main` before you open a PR.

The shared files get one owner, usually you. If a feature needs a new route, the feature session does everything except registering it, and tells you the line to add. It is far cheaper than a three-way merge in a lockfile.

You can also see a conflict coming. Since Git 2.38, git merge-tree merges two branches in memory and touches nothing on disk:

bash
git merge-tree --write-tree feat/auth feat/search

It exits non-zero and lists the conflicted files if the merge wouldn't be clean. For conflicts of meaning, merge both branches on a scratch branch and run the tests there before you review either one.

How do you stop two sessions doing the same task?#

Worktrees separate the files, not the intent. Tell two sessions to "fix the flaky checkout test" and both will, in different ways, and both will be correct. You find out when you review.

The fix is the one a human team uses: nobody starts work that somebody else holds. For one person juggling sessions, a file is enough:

md
<!-- TASKS.md -->
- [ ] checkout test flake    (unclaimed)
- [ ] search pagination      claimed: session-2, branch feat/search
- [ ] auth token refresh     claimed: session-1, branch feat/auth

The rule in your instructions is two lines: read TASKS.md before starting, and write your claim before touching code.

A markdown file is not atomic. Two sessions that read it in the same minute will both see "unclaimed". If you start sessions one at a time, that is fine. If they start together, name each session's task in its first prompt. When a session has to pass work to another, a handoff note with the branch and commit saves the next one from starting over.

How many Claude Code sessions can you run at once?#

For most people the number is about three, and the limit isn't the agents. It is you. Every session produces a diff that someone has to read, and reading doesn't parallelise. Past three, you start approving things you haven't understood; reviewing pull requests from several agents covers the order to read them in.

A few habits make three workable:

  • Give each session a task you can describe in two sentences.
  • Land the shared change first. If two features need a new field on User, merge that alone, then branch both from it.
  • Rebase at the start of every session: git fetch origin && git rebase origin/main.
  • Keep branches short. A branch that lives for a day conflicts far less than one that lives for a week.

Keeping track of the sessions themselves (names, resuming, which one is waiting for you) is its own problem; managing many Claude Code sessions covers it.

When this is not enough#

Parallel sessions only help when the work divides. A tightly coupled change, such as a refactor that touches every caller of a function, goes faster in one session than in three. Our page on splitting work between agents covers when splitting is the wrong call.

The setup also assumes one person starting every session. It strains when the sessions belong to different people on different machines: a TASKS.md only changes when somebody pulls it, and two agents can claim the same task in the same minute. That is the part Joxo handles. A second claim on a task is turned away with the name of whoever holds it, and a handoff with the branch and commit reaches the other person's agent on its next turn. One person on one machine doesn't need it. For the team version, read how to coordinate AI coding agents across a team.

Frequently asked questions#

Can two Claude Code sessions work in the same folder?#

They can, but they shouldn't edit code there at the same time. One session can test another's half-finished edit and act on it. Give each session its own git worktree on its own branch. Claude Code can create one for you with its worktree option, and each worktree keeps its files separate until you merge.

Do git worktrees prevent merge conflicts?#

No. Worktrees stop sessions overwriting each other's files while they work, but the branches still meet at merge time. Lockfiles, migrations and route tables conflict often, and some conflicts are about meaning, so git merges them cleanly and the tests fail afterwards. Name one owner for shared files and test the merged result before review.

How many Claude Code sessions should I run in parallel?#

About three for most people. The agents can do more, but every session produces a diff that a person has to read and understand, and review is the part that doesn't speed up. Past three, people start approving changes they haven't really read. Small, clearly described tasks and short-lived branches make three sessions manageable.

How do I stop two Claude Code sessions from doing the same task?#

Have each session claim its task before it starts. A shared task file where a session writes its name and branch works for one person who starts sessions one at a time. It is not atomic: two sessions reading it in the same minute can both take a task. When several people's agents share a project, a second claim has to be refused when it is made.

Something missing or wrong? Support reaches a person.