Claude Code worktrees: how to run parallel agents with git worktrees (2026)

Short answer: start each Claude Code session with claude --worktree <name> (or -w) and it works in its own copy of your project, under .claude/worktrees/<name>/, on its own branch. Two sessions in two worktrees can't overwrite each other's files. Add .claude/worktrees/ to your .gitignore, list the gitignored files each copy needs (like .env) in a .worktreeinclude file, and Claude Code cleans up when you exit.

This guide covers the whole workflow: starting, setting up, the desktop app, subagents, cleaning up and the errors people hit. It's all from Anthropic's documentation, checked on October 25, 2026. (I build Morphy, which also gives agents their own copy; it gets a mention near the end.)

What is a worktree, and how is it different from a branch?

A branch is a line of commits. A worktree is a folder with a branch checked out. Your project folder is already one worktree; git worktree adds more, each with its own files and its own branch, all sharing one repository history.

That's what parallel agents need. Two agents on two branches in the same folder still edit the same files, because a folder can only have one branch checked out at a time. Two agents in two worktrees each have their own files, and their commits land in the shared history straight away.

A few things that follow from it:

One branch, one worktree. Git refuses to check out a branch that another worktree already has checked out.
Cheaper than a second clone. A worktree shares the .git folder, so the history isn't copied, only the files.
Gitignored files aren't there. A worktree is a fresh checkout: no .env, no node_modules, no build output until you add them.

Start Claude Code in a worktree

claude --worktree feature-auth

Claude Code creates .claude/worktrees/feature-auth/ at your repository's root, on a new branch called worktree-feature-auth, and starts the session there. Open another terminal and run it with another name for a second agent. Leave the name out and Claude picks one, like bright-running-fox.

Already in a session? Ask Claude to "work in a worktree", and it makes one and moves in.

The first time in a folder, run plain claude once to accept the trust dialog; until you do, --worktree exits with an error asking you to.

Set it up once per project

Ignore the worktrees folder. Add .claude/worktrees/ to your .gitignore, or every worktree shows up as untracked files in your main checkout.
Bring your secrets along. Create .worktreeinclude in the project root, in .gitignore syntax. Files that match it and are gitignored get copied into every new worktree:
```
.env
.env.local
config/secrets.json
```
Deal with dependencies. Each worktree needs its own install: ask Claude to run it, or do it yourself in the worktree's folder. To share one big folder instead of installing it again, list it in your settings and Claude Code links it into each worktree:
```
{
  "worktree": {
    "symlinkDirectories": ["node_modules"]
  }
}
```
In a large monorepo, worktree.sparsePaths checks out only the folders you list, which makes new worktrees faster.

Choose what a worktree starts from

By default a new worktree branches from your repository's default branch on the remote (usually main), so it starts clean. Claude Code fetches it first if it hasn't in the last 24 hours. Two other options:

From your current work: set "worktree": { "baseRef": "head" } in your settings, and new worktrees carry your unpushed commits and current branch.
From a pull request: claude --worktree "#1234" (quoted, because of the #) fetches that pull request into .claude/worktrees/pr-1234. A GitHub pull request or GitLab merge request link works too.

baseRef can't name a branch. To start from a specific existing branch, use git yourself:

git worktree add ../my-app-bugfix fix-issue-456
cd ../my-app-bugfix
claude

Worktrees in the desktop app and VS Code

In the Claude desktop app, turn on Worktree before you start a session: click the project folder control under the prompt box (in the earlier layout, it's a worktree checkbox beside the branch name). It's off by default. Worktrees go in .claude/worktrees/ unless you set Worktree location in Settings → Claude Code, where a Branch prefix keeps Claude's branches together. .worktreeinclude works here too.

One thing to watch: when you archive a session, commit what you want to keep. A worktree with uncommitted changes stays on disk, but the app removes it about 30 days after the session was archived or last opened.

In VS Code, Anthropic's docs point to the same --worktree command: run it in VS Code's terminal, or open the worktree's folder in a new window.

Subagents and /batch in worktrees

Subagents can get worktrees too, so several of them can edit at once. Ask Claude to "use worktrees for your agents", or make it permanent for a custom subagent with one line in its frontmatter:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

A subagent's worktree is removed when it finishes without changes. For one big change, /batch does it all: Claude splits the work into 5 to 30 units and runs one background subagent per unit, each in its own worktree, testing and publishing its own change.

Agent teams are different: teammates work in the same files, and two editing one file overwrite each other, so give each teammate its own files. More on all of these in how to run multiple Claude Code agents.

What a worktree shares, and what Claude Code blocks

Worktrees of one repository share:

The .git folder, so a commit in one is visible from all of them.
Project plugins, installed once from the main checkout.
Your approvals. "Yes, and don't ask again" in a worktree is saved to the main checkout's settings, so it applies everywhere. (On Windows, the approval stays with that worktree.)
Skills, agents and commands from the main checkout, when the worktree has no .claude/skills of its own (for example because yours are gitignored).

While a session is in a worktree, Claude Code blocks edits to files in the main checkout, commands that run there, and git commands pointed back at it. It reads the command text, though, not every file a command writes, so a cp or a shell redirect into the main checkout isn't caught. Your normal permissions still apply to those.

Clean up and come back later

When you exit a worktree session, Claude Code checks for work that removing it would lose:

Nothing changed: the worktree and its branch are removed (a named session asks first).
There's work in it: you choose to keep or remove it. If you keep it, Claude Code prints the command to come back: claude --worktree feature-auth --resume.

Runs with -p don't clean up after themselves. Subagent and background-session worktrees are swept up after your cleanupPeriodDays, unless they still hold work. For anything left over:

git worktree list
git worktree remove .claude/worktrees/feature-auth

Add --force if it has uncommitted changes, and run git worktree unlock first if git says it's locked.

On Windows, mind links. Claude Code deletes only the link if a folder inside a worktree is a junction or symlink (since v2.1.205; older versions could delete the folder it pointed to). If you made a junction yourself, say to share node_modules, remove it with rmdir before you delete the worktree any other way.

Merge a worktree's work

A worktree's work is just a branch. Ask Claude in that session to commit and open a pull request, or merge it from your main checkout:

git merge worktree-feature-auth

Then exit the session or remove the worktree. If you open a pull request from it, reusing the name later starts fresh once that pull request is merged and its branch deleted.

Common errors

What you see	What it means	The fix
`--worktree` exits asking you to trust the folder	You haven't run Claude in this folder yet	Run `claude` once there and accept the trust dialog
Big files are tiny text files in the worktree	Git LFS was set up with `--local`, and Claude Code skips the repository's own filters	Run `git lfs pull` in the worktree
`Refusing to use <path> as an isolation worktree` … `launch from the parent checkout`	You started Claude from inside the worktree	Start it from the main checkout
Creating the worktree fails on a symlinked path	`.claude` or `.claude/worktrees` is a symlink	Remove the symlink and try again
`This repository is a partial clone`	Git couldn't fetch everything the worktree needs	Do what the message says, then run `claude --worktree` again from the same shell
`Error creating worktree: Failed to fetch PR/MR`	Git or ssh wanted a password or a new host confirmed	Load your key into `ssh-agent` and run `git fetch` once yourself

Anthropic's worktree troubleshooting covers the rarer ones.

Worktrees in other apps

Most apps for running several agents use worktrees under the hood:

Codex in the ChatGPT app gives a chat its own worktree, and Hand off moves it between your folder and the worktree. See Codex app vs Morphy.
Conductor (Mac only), Orca and Emdash make a worktree for every task, with review and pull requests. See the Conductor alternatives.
Morphy: any chat, on Claude or any other AI, can Work in its own copy, a worktree on a branch named morphy/ plus the chat's name. Your .env files come along, the copy lives in Morphy's data folder rather than your project, and Bring into puts its changes into your folder, uncommitted, to look over. See its own copy.

Questions

Where does Claude Code put worktrees? In .claude/worktrees/<name>/ at your repository's root, on a branch named worktree-<name>. The desktop app can use another folder (Worktree location); for the command line, create the worktree with git worktree add wherever you like, or use a WorktreeCreate hook.

Does a worktree copy node_modules and .env? No. List .env and other gitignored files in .worktreeinclude to copy them, and install dependencies in each worktree or link them with worktree.symlinkDirectories.

Can two worktrees use the same branch? No. Git won't check out a branch that another worktree has checked out, which is what keeps two agents apart.

Do worktrees take a lot of disk space? Each one is a full set of your project's files, but not another copy of the history. Large folders like node_modules are what add up; link them instead.

Do worktrees work without git? Not by default. For SVN, Perforce or Mercurial, WorktreeCreate and WorktreeRemove hooks replace the git part.

How many worktrees can I run? As many as your computer and your plan allow. Every session draws from the same Claude plan, so five at once use it about five times as fast: see Claude Code's usage limits.

References

Anthropic: run parallel sessions with worktrees, worktree settings, desktop app worktrees, VS Code, commands (/batch), subagents, agent teams
Git: git worktree
Morphy: its own copy