Git Worktree Claude Code Workflow: How to Run Parallel Sessions Without Collisions

Learn how a git worktree claude code setup runs parallel sessions on one repo without collisions, then keep them always-on from $3.99/month. See the full flow.

Published on

•

Git Worktree Claude Code Workflow: How to Run Parallel Sessions Without Collisions
Do not index
A git worktree claude code setup gives each Claude Code session its own checkout of the same repository, so three agents can work on three branches at once without overwriting each other's files. You create the checkouts with git worktree add or with Claude Code's native --worktree flag, then launch one session per directory. To keep those sessions running after you close your laptop, we recommend Agent 37, a managed hosting platform with persistent, always-on instances from $3.99 per month managed for OpenClaw and Hermes, with Claude Code provisioned on the same persistent instances through one API call. Agent 37 is not a worktree manager and not a Claude Code plugin; it is the always-on computer your worktrees and sessions live on.
Key takeaways
  • Worktrees share one object database: every worktree is a separate working directory on the same .git, and git refuses to check out the same branch in two worktrees at once, which is exactly the guard that stops parallel sessions from colliding.
  • Claude Code has a native flag: claude --worktree <name> (short form -w) creates a worktree inside the repo's .claude/worktrees/ folder, branched from the current HEAD, and offers to remove it when the session ends without changes.
  • Untracked files are never copied: .env, node_modules, and .claude/settings.local.json must be recreated in each worktree, while .git/hooks is shared by all of them.
  • Agent 37 keeps sessions alive: persistent instances from $3.99 per month managed for OpenClaw and Hermes, Claude Code provisioned through one API call, isolated containers, and API keys that go directly to Anthropic or OpenAI.
  • Parallel is not always cheaper: an always-on worker on the smallest sensible hyperscaler VM lands near $25 a month before storage and networking, so the decision to run several sessions should follow the number of independent, verifiable tasks you actually have.
notion image

Why do multiple Claude Code sessions collide on one repository?

Two Claude Code sessions in the same directory share one working tree, so when the first session edits auth.ts and the second runs git checkout other-branch, the first session's uncommitted work is swapped out from under it. Worktrees fix this by giving each branch its own directory while sharing commits, refs, and the object store.
The failure is not theoretical. A normal clone has one index and one HEAD, and both sessions write to them. One agent stages files the other did not touch, one runs tests against a half-edited tree, and the resulting commit mixes two tasks.
The official git worktree reference describes a worktree as a linked working tree with its own HEAD and index, attached to the main repository. That is the whole trick: each Claude Code process gets a private directory and a private branch, and git itself enforces that no branch is checked out twice.
The demand for this is real. The Stack Overflow 2025 Developer Survey found 84% of developers use or plan to use AI tools, while 46% distrust the accuracy of their output. Isolation per task is how you review one agent's work without untangling it from another's.

How do you create a git worktree for a Claude Code session?

Run git worktree add from the main checkout with a sibling directory and a branch. Use -b to create a new branch, pass an existing branch name to reuse one, and fetch a pull request into a local branch first if you want to work on an open PR. Keep worktree folders outside the main checkout or ignored inside it.
For a brand-new feature branch, start from main and name the directory after the branch:
cd ~/code/app
git worktree add -b feat/billing-retry ../app-billing-retry main
cd ../app-billing-retry && claude
For a branch that already exists locally or on the remote, omit -b. Git will create the worktree with that branch checked out, as long as no other worktree already has it:
git worktree add ../app-fix-login fix/login-timeout
For an open pull request, fetch the PR head into a local branch and then add the worktree. The pull/<n>/head ref works on GitHub without any extra tooling:
git fetch origin pull/482/head:pr-482
git worktree add ../app-pr-482 pr-482
If you expect to keep many worktrees around, the bare-repo pattern is cleaner. Clone with --bare into app/.bare, point a .git file at it, and create every worktree as a sibling under app/. There is no privileged main checkout, so you never accidentally run a session in the wrong place.

What does the Claude Code --worktree flag do, and when is it better than manual setup?

Starting Claude Code with claude --worktree <name> (or -w) creates a git worktree under .claude/worktrees/<name> inside the repository, branched from your current HEAD, and opens the session there. When the session ends with no changes, Claude Code offers to remove the worktree. It is the fastest route for short, throwaway tasks.
The flag removes three manual steps: picking a directory, inventing a branch name, and remembering to delete the worktree later. Anthropic documents the flag in the Claude Code CLI reference, and the broader parallel workflow in its common workflows guide. Confirm current behavior there, because the flag is newer than most community scripts and has changed between releases.
It has limits. The worktree lives inside the repo, so make sure .claude/worktrees/ is ignored or you will see it as untracked noise. It does not copy .env files, install dependencies, or pick a free port, which is the work a custom script handles. And it branches from HEAD, so if you are standing on a stale branch, the new worktree inherits that.
A simple decision rule: use --worktree for tasks under an hour that need no running services. Use manual git worktree add plus a script when the task needs a dev server, a database, or a PR branch.

Should parallel worktree sessions run on your laptop or on an always-on machine?

A laptop works for two or three sessions during the day, but every worktree closes when the lid does, and long jobs die mid-run. An always-on Linux instance keeps the repo, caches, and sessions in place between runs. We recommend Agent 37 for this because the instance persists and your API keys go directly to Anthropic or OpenAI.
Parallel sessions are the point where local hardware starts to hurt. Each Claude Code process holds a terminal, a node process for the dev server, and often a test runner; three of those on a laptop compete for CPU and fans. The Agent 37 Cloud instance for Claude Code is a persistent machine that still has the repo and sessions when you return, and you can read how it works on the Claude Code hosting on a persistent cloud page.
The workflow is the same one you would run locally. You SSH into the instance with your existing keypair, create worktrees as siblings, and start one Claude session per tmux window. Agent 37 also provides a browser terminal, a visual file browser, and a live Linux desktop via noVNC, so you can check a worktree from a phone without opening a shell.
Agent 37 does not run Claude Code for you, does not manage worktrees, and does not replace your Anthropic plan. It is the computer underneath, with isolated containers, automatic runtime updates, and security patches. Each instance runs in its own isolated container, which is the same per-task isolation worktrees provide, one layer down.
notion image

Can a slash command create the worktree and launch Claude automatically?

Yes. Claude Code reads custom slash commands from .claude/commands/*.md, and the $ARGUMENTS placeholder passes whatever you type after the command. A /worktree command can shell out to a script that adds the worktree, copies untracked config, installs dependencies, and opens a new tmux window with claude already running inside it.
First, the script. Save it as scripts/wt.sh and make it executable:
#!/usr/bin/env bash
set -euo pipefail
name="$1"; base="${2:-main}"
root=$(git rev-parse --show-toplevel)
dir="$(dirname "$root")/$(basename "$root")-$name"
git worktree add -b "$name" "$dir" "$base"
cp "$root/.env" "$dir/.env" 2>/dev/null || true
[ -d "$root/.claude" ] && cp -r "$root/.claude" "$dir/.claude"
(cd "$dir" && npm ci --silent)
tmux new-window -n "$name" -c "$dir" "claude"
Then the slash command at .claude/commands/worktree.md:
---
allowed-tools: Bash(scripts/wt.sh:*)
description: Create a worktree and start Claude in it
---
Run `scripts/wt.sh $ARGUMENTS` and report the new directory path.
Typing /worktree feat/search-index now does the entire setup. For subagents, Claude Code also accepts isolation: worktree in an agent definition, which gives a spawned subagent its own worktree without a terminal at all; check the current subagent docs for the exact frontmatter.

How should .env files, dependencies, and dev-server ports be handled across worktrees?

Git copies only tracked files into a new worktree, so every untracked asset is missing on day one: .env, node_modules, local caches, and .claude/settings.local.json. Copy or symlink config, reinstall dependencies, and assign each worktree a unique port and database name, or two sessions will fight over port 3000 and the same local database.
For environment files, copying is safer than symlinking because each worktree can then override PORT and DATABASE_URL. A convention that scales is one line per worktree:
echo "PORT=3001" >> ../app-billing-retry/.env
echo "DATABASE_URL=postgres://localhost/app_billing_retry" >> ../app-billing-retry/.env
Dependencies are the disk cost. Three worktrees of a typical JavaScript app mean three node_modules folders, often several hundred megabytes each. pnpm's content-addressable store shares packages across them, which is the single biggest saver; with npm or yarn, budget the disk and prune worktrees aggressively.
Docker Compose users should pass a distinct project name per worktree with docker compose -p app-billing-retry up, so containers and volumes do not collide. Git hooks are a quieter trap: .git/hooks is shared by every worktree, so a hook that assumes a specific path will fire in all of them.

How does CLAUDE.md and Claude Code context behave across worktrees?

Claude Code loads CLAUDE.md from the current directory and every parent up to the filesystem root, plus the tracked .claude/ folder in the checkout. A tracked CLAUDE.md therefore appears in every worktree automatically, while untracked local memory, settings, and todo files do not travel. Each session starts with a fresh conversation context.
The walk-up rule has a side effect when you use --worktree. Because .claude/worktrees/<name> sits inside the main repo, the session sees the worktree's own CLAUDE.md and then the parent repo's copy as it walks up, which is usually identical but can double-load instructions if the two diverge. Sibling directories avoid that.
Keep per-task context in the worktree, not in the shared file. A short TASK.md at the worktree root with the goal, the acceptance test, and files in scope gives each session a bounded brief. Context size matters too: a session that has read half the repo responds slower and loses earlier instructions, so prefer three narrow sessions to one that spans everything.
Memory files that Claude Code writes locally stay in the worktree where they were created. If one session discovers a convention the others need, commit it to the tracked CLAUDE.md and let the other worktrees pull it.
notion image

What is the full flow from parallel sessions through merge, conflicts, and cleanup?

Each session commits on its own branch, rebases onto main before merging, runs the test suite in its own worktree, and opens a pull request. Conflicts between parallel sessions surface at rebase time, where the session that touched the file resolves them. After merge, remove the worktree, delete the branch, and run git worktree prune.
The commands, in order, from inside a worktree whose task is done:
git add -A && git commit -m "feat: retry failed billing webhooks"
git fetch origin && git rebase origin/main
npm test
git push -u origin feat/billing-retry
gh pr create --fill
When two parallel sessions edit the same file, the second rebase will stop on a conflict. Resolve it in that worktree, with the Claude session that owns the branch, because it has the context for why the lines changed. Asking a third session to referee a conflict it did not create is where most mixed-up commits come from.
Cleanup after merge, run from the main checkout:
git worktree list
git worktree remove ../app-billing-retry
git branch -d feat/billing-retry
git worktree prune
git worktree list is the audit command; run it weekly and anything older than the last merged PR is a candidate for removal. prune only cleans metadata for directories that were deleted by hand, so it is a safety net rather than a replacement for remove.

Which worktree managers and tools are worth using instead of raw git commands?

Four layers exist: Claude Code's built-in --worktree flag, a custom script or slash command you maintain, open-source CLIs such as agenttools/worktree, and desktop managers such as Conductor. Agent 37 sits underneath all of them as the always-on host. Pick the lightest layer that covers env setup and port assignment for your stack.
Option
Best for
Pricing or format
Standout limit
Agent 37
Keeping worktrees and sessions alive after you log off
Persistent instances from $3.99 per month managed for OpenClaw and Hermes; Claude Code provisioned through one API call
Not a worktree manager; you still run the git commands
Claude Code --worktree
Short tasks with no services
Included with Claude Code
No env copy, no port assignment, worktree nested in repo
Custom script or slash command
Teams with a fixed stack and port scheme
Free, maintained by you
Breaks when the stack changes; one more script to own
agenttools/worktree
CLI users who want naming and cleanup handled
Open-source CLI on GitHub
Terminal only; confirm current features in the README
Conductor
Visual management of many sessions
Desktop app; check the vendor site for platform support and pricing
Tied to its own UI rather than your terminal
Incident.io's engineering team published a widely shared write-up of running Claude Code across worktrees, which is why "incident io git worktree" shows up as a related search; their pattern is close to the script above. GitHub-linked tooling that creates a worktree per issue or PR is useful once you have more than a handful of open tasks.

When are parallel Claude Code sessions worth the cost, and how many is practical?

Parallel sessions pay off when you have two or more tasks that are independent, well specified, and verifiable by tests. Three to four worktrees is the practical ceiling for one person to review. Below that threshold, a single session is cheaper in tokens, disk, and attention; above it, review becomes the bottleneck rather than generation.
The costs are concrete. Each session consumes its own context and tokens, each worktree duplicates dependencies on disk, and each running dev server takes a port and memory. Four sessions on one task rarely finish faster than one, because they fight over the same files at rebase time.
Compute is the hidden line item. An always-on worker on the smallest sensible hyperscaler VM lands near $25 a month before storage, schedulers, and networking. That gap is what managed always-on AI agent hosting closes, with isolated containers and automatic runtime updates included rather than assembled by hand.
A usable rule: if you can write each task's acceptance test before starting, run them in parallel. If you cannot, run one session and let it explore.

How did we compare these options?

We compared the current Claude Code CLI and common-workflows documentation, the official git worktree reference, and the README or product pages of the third-party tools named above, looking at what each creates, what it copies, how it cleans up, and whether it publishes a price.

How do you get started with Agent 37 for parallel Claude Code sessions?

Provision a persistent Claude Code instance through one API call, SSH in with your existing keypair, create your worktrees as siblings, and start one session per tmux window. The repo, caches, and sessions stay on the machine when you close your laptop, and API keys go directly to Anthropic or OpenAI.
Set up Claude Code hosting on an always-on Agent 37 instance and run your first parallel worktree session today.

What do people also ask?

How do I run multiple Claude Code sessions in parallel on the same repository without conflicts?
Create one git worktree per task with git worktree add -b branch ../dir main, or start each session with claude --worktree name. Each session then has its own directory, branch, and index, and git refuses to check out the same branch twice, so edits cannot collide until you deliberately merge.
What does the --worktree flag in Claude Code do, and when should I use it instead of git worktree add?
claude --worktree name (or -w) creates a worktree under .claude/worktrees/name branched from your current HEAD, starts the session there, and offers to remove it if the session ends with no changes. Use it for short tasks with no running services; use manual git worktree add plus a script when you need .env copies, dependencies, or a dev server on its own port.
How do I create a worktree for an existing branch or an open pull request?
For an existing branch, run git worktree add ../dir branch-name without -b. For a pull request on GitHub, fetch it first with git fetch origin pull/123/head:pr-123, then git worktree add ../app-pr-123 pr-123. The branch must not already be checked out in another worktree.
How do I handle .env files, node_modules, and dev-server ports across worktrees?
Git only copies tracked files, so copy .env into each worktree, reinstall dependencies there, and append a unique PORT and DATABASEURL per worktree. pnpm's shared store cuts the disk cost of duplicate nodemodules, and Docker Compose users should pass a distinct -p project name so containers do not collide.
How do I list, clean up, and remove worktrees after a task is merged?
Run git worktree list to audit, git worktree remove ../dir to delete a finished worktree, git branch -d branch to drop the merged branch, and git worktree prune to clear metadata for directories removed by hand. Agent 37 instances keep remaining worktrees in place between sessions, so cleanup is a deliberate step rather than a side effect of logging off.