Claude Code Worktrees: Run Parallel Agents Safely
9 min read
Key takeaways
- A git worktree gives each Claude Code agent its own checkout, branch, and index, so parallel sessions cannot overwrite each other's edits.
- Worktrees do not copy untracked files like .env or node_modules, so symlink secrets and budget one dependency install per worktree.
- The three recurring failure modes are stale worktrees, shared untracked files, and merge conflicts between agent runs; each has a paste-ready fix.
- Merge branches one at a time, rebasing each onto current main immediately before merging, and merge the least contested branch first.
- Worktrees pay off for many independent code-only tasks, but add overhead for single agents or tasks coupled to shared infrastructure.
Claude Code worktrees let you run multiple agents in parallel on one repo by giving each session its own checkout, branch, and working directory, so edits never collide. This guide covers the exact setup commands, how to isolate branches, and the three failure modes that break parallel runs: stale worktrees, shared untracked files like .env, and merge conflicts between agent runs, each with a fix you can paste.
What are git worktrees and why do they matter for Claude Code?
A git worktree is a second checkout of the same repository in its own directory, on its own branch, sharing one .git store. The official Git documentation defines the command semantics: git worktree add ../feature-x feature-x gives you a full working directory without a second clone.
For Claude Code, that matters because each agent gets an isolated branch and filesystem, so two parallel runs cannot stomp on each other's uncommitted edits. You can run one session per worktree across six terminals, review each diff independently, and merge branches back one at a time.
Without worktrees, parallel agents on a shared checkout collide on the same files and the same HEAD. With them, isolation is the default. We cover setup and failure modes in the rest of this walkthrough, with more on coordination workflows at https://aerunit.ai/blog.
How do you set up a worktree for a Claude Code session?
The basic setup
From your repo root:
git worktree add ../myrepo-auth-fix -b fix/auth-redirect
cd ../myrepo-auth-fix
claude
That creates a sibling directory with its own checked-out branch, then launches Claude Code inside it. Each agent gets its own directory, its own branch, and its own index. To add another agent, repeat with a new branch name: git worktree add ../myrepo-payments -b feat/payments-retry. List everything with git worktree list and remove a finished one with git worktree remove ../myrepo-auth-fix.
What Claude Code sees inside a worktree
The long paragraph worth quoting on its own: a worktree gives Claude Code a full checkout, not a partial view. Tracked files are complete and consistent with the branch you checked out, so the agent can read, edit, and run tests exactly as it would in your main clone. What it does not inherit is your untracked state: .env, node_modules, local config, build artifacts, and anything else git ignores stay behind in the original directory. That isolation is the point, but it trips people up on the first run because the agent reports missing environment variables or spends minutes reinstalling dependencies. The fix is to copy or symlink the files you actually need (cp ../myrepo/.env .), install dependencies once per worktree, and accept that per-worktree setup cost as the price of not having two agents editing the same file. If you want a checklist for the per-worktree prep steps, we keep one at https://aerunit.ai/guides.
How do you run multiple Claude Code agents in parallel worktrees without conflicts?
One worktree per Linear ticket
Map every Linear ticket to its own worktree and branch, created before the agent starts:
git worktree add ../repo-PROJ-142 -b agent/PROJ-142
cd ../repo-PROJ-142 && claude
The agent gets an isolated checkout, so git status in one session never shows another agent's staged files. If the ticket needs a shared package change, note it in the Linear ticket and resolve it at merge time rather than letting two agents edit the same file in parallel.
Naming conventions that survive a week of runs
Use ../repo-<ticket-key> for paths and agent/<ticket-key> for branches, always derived from the Linear ID. After six terminals and a few days, you need to answer "which worktree belongs to which run?" from the directory name alone. Delete the worktree when you merge the branch; a stale ../repo-PROJ-87 that someone reuses mid-run is the classic collision.
For Claude Code behavior across sessions, Anthropic's docs (docs.anthropic.com) cover headless and multi-session usage. When runs touch multiple repos, cross-repo changes with coding agents covers coordinating branches across them.
What breaks when agents share a repo, and how do worktrees prevent it?
One checkout, multiple agents, and three failure modes keep showing up.
Stale worktrees
A worktree left over from yesterday's run still has an old branch checked out. You start a new agent there, it commits against a stale base, and your merge is full of surprises. Fix: before each run, run git worktree remove ../wt-old-task and create fresh with git worktree add ../wt-task -b task-branch origin/main. Never reuse a worktree for a new task.
Shared untracked files
Untracked files like .env, local.db, or build output live in the working directory, not git, so worktrees do not copy them. Two agents writing the same dev.log or one agent missing a .env it needs both trace back here. Fix: keep secrets in one place and symlink them into each worktree, and add generated files to .gitignore so agents never treat them as deliverables.
Merge conflicts between agent runs
Two agents both touching package.json or the same module produce diffs that conflict on merge, even though each run passed locally. Worktrees do not prevent this; they just make it visible early, since each diff is isolated and reviewable. Fix: scope tasks so file ownership does not overlap, and merge small branches one at a time.
| Failure mode | Symptom | Fix |
|---|---|---|
| Stale worktree | Agent commits against old base | Remove and recreate per task |
| Shared untracked files | Missing .env, clobbered logs | Symlink secrets, .gitignore generated files |
| Merge conflicts | Two diffs touch the same files | Non-overlapping task scope, merge serially |
Isolation solves the mechanical half. Knowing which agent finished, whether the diff meets acceptance criteria, and what to queue next is the coordination half. We built Aerunit notes and patterns around that problem; the honest limitation is that no tooling removes the merge-conflict risk above, it only surfaces it sooner.
How do you merge worktree changes back after Claude Code finishes?
The agent finishing is not the same as the work landing. Each worktree has its own branch, so you merge (or squash-merge) that branch into main from the main checkout, then remove the worktree. The step that matters is the one before that: review the diff.
Review the diff before merging
Run git diff main...branch-name and read it. Claude Code agents will happily touch files outside the scope you gave them, and a diff is the only record of what actually changed. One practitioner described the failure plainly: "I was the glue between every step, I did it slightly differently each time, and when something went wrong I had no record of where" (dev.to). If the work is headed to a pull request anyway, our notes on reviewing agent pull requests cover what to check before approving.
Rebase order matters with parallel runs
With several agents merging the same day, merge order decides your conflicts. Rebase each branch onto the current main immediately before merging, one at a time, so each agent's branch sees the previous merges. Merge the smallest, least contested branch first; save the branch that touches shared files (lockfiles, shared types, config) for last, when you can resolve its conflicts against everything already landed.
How do you clean up worktrees after agent runs complete?
List worktrees and their status first, so you prune only finished runs:
git worktree list
Then remove a merged one and delete its branch:
git worktree remove ../feature-auth
git branch -d feature-auth
If a worktree has uncommitted agent changes you have already reviewed the diff on and rejected, force it: git worktree remove --force ../feature-auth. Use git worktree prune only for worktrees whose directories you deleted manually; it clears stale references, it does not touch live ones.
The habit that keeps the list usable: remove the worktree the moment you merge or reject the run, not "later". A ~/worktrees directory with 15 stale checkouts means you stop trusting git worktree list as your source of truth for what is actually running.
When are worktrees the wrong choice for Claude Code workflows?
Worktrees isolate tracked files, but they do not isolate anything outside the repo. If your agents need a shared database, a running dev server, or a seeded test environment, each worktree either duplicates that setup or fights over the same instance. A worktree shares the same repository, so hooks and large generated assets still cost you per checkout.
They also add overhead when tasks are small. Spinning up a worktree, branch, and cleanup cycle for a one-file fix costs more than the collision risk it removes. The same goes for sequential work: if you run one agent at a time anyway, a plain branch gives you the same isolation with less ceremony.
The signal is task size and shared-state coupling. Many independent, code-only tasks: worktrees pay. One agent, or tasks touching shared infrastructure: they don't.
How do you queue the next prompt without being the bottleneck?
Once agents run in parallel worktrees, the constraint moves from compute to you: six terminals, and every finished run waits for a human to paste the next prompt. The fix is a queue per worktree, filled from your Linear issues, so the agent pulls the next scoped task the moment the current one lands. Write each task with acceptance criteria and the files it may touch, and the queue degrades gracefully when a step goes sideways, because the next prompt is scoped against the branch, not your memory of it.
This is where Aerunit fits: it sits between Linear and Cursor Cloud Agents, keeps a queue per worktree, and gives you cross-repo awareness so one agent's changes are visible to the others before they collide. Team credit-pool pricing bills the team, not per seat.
Honest limits: Aerunit assumes you already plan in Linear and run Cursor Cloud Agents specifically. If your agents run locally via Claude Code in raw worktrees, a simple per-branch prompt file and a polling script may be all you need; the queue matters more than the tool that holds it.
FAQ
Does Claude Code have a built-in worktrees skill or command?
No. Claude Code has no worktree command of its own; it simply runs inside whatever directory you launch it from. Worktree creation, branch naming, and cleanup are plain git operations you handle yourself. Launch claude after git worktree add and the agent gets an isolated checkout with its own branch and index.
Do git worktrees duplicate node_modules or share dependencies between agent sessions?
They duplicate them. A worktree is a full checkout, so git-ignored files like node_modules stay behind in the original directory and each worktree needs its own install. That per-worktree setup cost is the price of isolation. Copying or symlinking .env and running one install per worktree is the standard fix.
Can two Claude Code agents work on the same branch in different worktrees?
Git blocks checking out the same branch in two worktrees at once, and you should not want to. Same-branch runs recreate the collision worktrees exist to prevent. Give each agent its own branch, such as agent/PROJ-142, and keep file ownership non-overlapping so merges stay clean.
How many worktrees can I run before my machine slows down?
Git imposes no practical limit; the cost comes from each checkout's dependencies, build artifacts, and running agents, not from worktrees themselves. Six parallel sessions with per-worktree node_modules installs and test runs is a realistic ceiling on a laptop. Beyond that, disk usage and CPU contention, not git, become the constraint.