Claude Code worktrees: how to run coding agents in parallel

What is a git worktree?

A git worktree is a second working copy of the same repo, checked out to its own folder on its own branch. Every worktree shares one .git history, so they're cheap to make. Git won't check out one branch in two worktrees at once, which is what keeps parallel agents apart. The git docs cover git worktree add, list, remove and prune.

How do I run Claude Code in a worktree?

Pass --worktree with a name. From Claude Code's worktrees docs:

claude --worktree feature-auth
claude -w bugfix-checkout

• Where it goes: .claude/worktrees/<name>/ at your repo root, on a new branch called worktree-<name>. Leave out the name and Claude Code picks one.
• What it branches from: your remote's default branch. Set worktree.baseRef to "head" to branch from your local HEAD instead.
• A pull request: claude --worktree "#1234" checks out that PR into .claude/worktrees/pr-1234.
• More agents: run the command again in another terminal with a different name. Each one is its own session.

The flag arrived in Claude Code 2.1.49, according to its changelog. Add .claude/worktrees/ to your .gitignore, as the docs suggest.

What do I need to set up in each worktree?

A worktree is a fresh checkout. That has three consequences:

• Install dependencies again. Run npm install or your equivalent inside each worktree.
• Your .env isn't there. Gitignored files aren't copied. List them in a .worktreeinclude file, in .gitignore syntax, and Claude Code copies them in.
• The repo needs at least one commit before a worktree can branch from it.

Two agents can still clash outside git. If both start a dev server on port 3000, one fails, so give each worktree its own port.

How do I clean up Claude Code worktrees?

When you leave an interactive session:

• No changes, no name: Claude Code removes the worktree and its branch.
• Named, or with changes or commits: it asks whether to keep it. If you keep it, it prints claude --worktree <name> --resume to come back later.
• Non-interactive runs (claude -p): nothing is cleaned up. Remove them yourself with git worktree remove.

Can I create the worktrees myself?

Yes. Plain git works, and you start Claude Code inside each folder:

git worktree add ../project-feature-a -b feature-a
cd ../project-feature-a && claude

git worktree list
git worktree remove ../project-feature-a

Does the Claude Code desktop app use worktrees?

Only when you turn it on. The desktop app runs several sessions side by side in its sidebar, and Worktree is off by default. Switch it on and each session gets its own worktree in <project-root>/.claude/worktrees/, with an optional branch prefix. A worktree left on disk is removed about 30 days after its session is archived or last opened, whichever is later. Commit untracked files you want to keep, since the app can delete them. The app runs on macOS and Windows, with Linux in beta.

How do Codex worktrees work?

The Codex app has a Worktree option under the composer. Codex creates the worktree in $CODEX_HOME/worktrees in detached HEAD, and Create branch here turns it into a branch you name. Hand off moves a chat between your local checkout and a background worktree. Codex keeps the 15 most recent worktrees and snapshots each one before deleting it. Details are in Codex's worktree docs.

In the Codex CLI, --worktree starts a session in a new managed worktree, as in codex exec --worktree "implement the next step". It's been on by default since 0.156.0, released September 22, 2026.

Worktrees, subagents and agent teams

Subagents can use worktrees too: set isolation: worktree in an agent's front matter. The agent teams docs cover the rest.

Worktrees on your laptop or agents in the cloud?

Worktrees run on your machine, so your laptop has to stay on and every agent shares its CPU, memory and ports. Apps like Conductor wrapped this workflow in a Mac app. Meta bought Conductor in November 2026, and its cloud shuts down on November 20. Conductor alternatives lists the desktop apps that still do this, and Conductor vs Claude Code shows how much Claude Code now does on its own.

Cloud agents skip worktrees. Each task gets its own machine:

• Claude Code on the web: each claude --cloud "..." command starts its own cloud session. They share your plan's rate limits, so parallel sessions use them up faster (docs).
• Codex cloud: each task gets its own workspace and keeps working while your computer sleeps (docs).
• Buildful: each task gets its own private cloud sandbox and ends in a pull request.

Where Buildful fits

Buildful runs tasks in parallel without worktrees. Each task gets a fresh clone in its own cloud sandbox, with your repo's setup commands and environment variables, so there's nothing to install again and no ports to share. It runs your checks, tests UI changes in a real browser and records it, and opens a pull request on GitHub. Smart Mode picks the right open-weight model for each task. On Pro and Team, you can also pick a frontier model like Claude or GPT, with prepaid credit or your own API key. Pro is $10 a month for 1,000 tasks, and Team is $40 for 3,000 shared by the team (pricing). Buildful vs Claude Code and Buildful vs Conductor have the full comparisons.

Frequently asked questions

How do I run multiple Claude Code agents at once?

Open a terminal per agent and run claude --worktree <name> in each, with a different name every time. Each session works in its own git worktree and branch, so their edits don't collide.

What does claude --worktree do?

It starts Claude Code in a new git worktree at .claude/worktrees/<name>/, on a branch called worktree-<name>. When you exit, Claude Code removes it if nothing changed, or asks whether to keep it.

Does a Claude Code worktree copy my .env file?

No. A worktree is a fresh checkout, so gitignored files like .env are missing. List them in a .worktreeinclude file and Claude Code copies them in.

How do I delete a Claude Code worktree?

Exit the session and choose to remove it, or run git worktree remove <path>. Worktrees from claude -p runs are never removed automatically.

Can two worktrees use the same branch?

No. Git refuses to check out a branch that another worktree already has, unless you force it. Give each agent its own branch.

Do Claude Code and Codex worktrees work the same way?

Mostly. Both give each session its own checkout. Claude Code puts worktrees in .claude/worktrees/ on worktree-<name> branches, and Codex puts them in $CODEX_HOME/worktrees in detached HEAD until you create a branch.