Skip to main content
Back to Blog
· Futurist Systems

How do we stop parallel Claude Code sessions from overwriting each other?

Give every session its own git worktree and branch, stage files by path, and let a hook announce who is working on what. The failure modes we hit running many sessions on one machine, and the rules that fixed them.

Claude Code git worktree parallel sessions team setup

Give each session its own checkout. Two Claude Code sessions in the same working directory share one index and one set of files, so the second session’s git add, git checkout or git commit -a picks up the first session’s half-finished edits. A git worktree per session, one branch per worktree, and staging by explicit path remove the problem; a small session-registration hook makes the remaining collisions visible before they happen.

What actually goes wrong

We run several sessions at once on a single machine, and the collisions were always one of these:

  • Swept commits. A session ran git commit -a and shipped another session’s uncommitted edits to CLAUDE.md and a docs file inside an unrelated pull request. The diff looked fine to its author because the foreign files were already in the tree.
  • Branch flips under a running session. Session A runs git checkout main to start new work while session B is mid-edit on a feature branch. Session B’s next file read sees main, not its branch.
  • Blocked rebases. A rebase in the shared tree refuses to start because another session left the tree dirty.
  • Format hooks touching the wrong file. A post-edit formatter that reads its target from an environment variable Claude Code never sets will run with an empty argument and reformat whatever it finds. Reading the path from the hook’s stdin payload scopes it to the file that was just edited.

None of these are Claude Code bugs. They are what happens when two git clients share one directory.

Rule 1: one worktree per session

git worktree gives each session a separate directory with its own checked-out branch, sharing the same .git object store:

git worktree add /path/to/worktrees/feat-pricing -b feat/pricing main
cd /path/to/worktrees/feat-pricing && claude

Each session now has its own index, its own HEAD and its own untracked files. A git checkout in one worktree cannot move another.

Claude Code can do this step for you. claude --worktree <name> (short form -w) creates .claude/worktrees/<name> on a branch called worktree-<name> and starts the session inside it. A .worktreeinclude file at the repo root lists gitignored files that should be copied into each new worktree, such as .env; it is for small config files, not for node_modules. A subagent can get the same isolation by being launched with isolation: worktree, so a parallel fan-out of agents never shares one checkout either.

Two costs to plan for:

  1. Dependencies. A fresh worktree has no node_modules, whichever way it was created. Either run the install step in each worktree or point the build at a shared cache. Our pre-push hook builds the project, so a worktree without dependencies fails on push, not on merge.
  2. Disk. Worktrees that nobody removes pile up. We remove a worktree in the same turn its pull request is merged (git worktree remove <path>; the branch stays), and a weekly job removes any clean, fully pushed worktree that was forgotten.

Rule 2: one branch per task, named for the task

feat/<short-description> or fix/<short-description>, created from an up-to-date main. Our root CLAUDE.md spells out the sequence so every session follows the same one:

git checkout main && git pull --ff-only
git checkout -b feat/<short-description>

Nobody, human or agent, pushes to main; a pull request plus a merge script is the only path. With branches named for tasks, a second session can tell at a glance whether a branch belongs to someone else’s open work.

Rule 3: stage by path, never by sweep

This one is in our project memory because it bit us: no git commit -a, no git add . in a shared tree. Stage the files the task changed, by name:

git add src/content/blog/new-post.md docs/standups/2026-11-09.md
git commit -m "docs(blog): add answer page on parallel sessions"

Even with worktrees in place, keep the rule. It costs one line and it is the only guard that still works when someone runs a quick fix directly in the main checkout.

Rule 4: let sessions announce themselves

A SessionStart hook in .claude/settings.json can run a small script that writes a marker file with the session’s repo, branch and current task; a SessionEnd hook removes it. Our registration script prints the other active sessions and what each one is doing when a new session starts, so a session about to touch a shared file sees “another session is editing the pricing page” before it starts. The hook entry is two lines:

"SessionStart": [{ "hooks": [{ "type": "command", "command": "\"$HOME\"/.claude/scripts/session-coordinate.sh register" }] }]

The script itself is yours to write; the point is that a session’s first output includes who else is active.

Rule 5: shared state files get a timestamp check

Some files are written by every session: a task tracker, a memory index, a standup log. A worktree does not protect those if they live outside the repo or are merged by every branch. Our rule: read the file’s modification time right before writing, and if it changed since the session last read it, re-read and merge the addition instead of writing over it. It is a cheap stand-in for a lock.

Checklist

  1. Every session starts in its own worktree, on its own branch, from a fresh main.
  2. git add names files; git commit -a and git add . are banned in the repo rules.
  3. A SessionStart hook registers the session and lists the others.
  4. Shared tracker and memory files are checked by mtime before every write.
  5. Worktrees are removed when the pull request merges, with a weekly sweep as backstop.
  6. The rules live in CLAUDE.md and .claude/settings.json, so a new teammate inherits them by cloning.

If you want these rules installed across your repositories rather than written up, that is what our Claude Code fleet setup does.

Ready to automate your business?

Get a free workflow analysis to discover your highest-ROI automation opportunities.