Claude Code worktrees: parallel agents without stepping on each other

Running two Claude Code sessions on the same repo used to be a mess. One agent starts editing a file, the other reads it mid-edit, and now you're debugging a merge you never asked for. The workaround was git stash, second clone, separate directories, manual branch juggling. None of it felt good.

Claude Code worktrees fix this at the layer it should have been fixed at: the filesystem. With the --worktree flag, each session gets its own checkout, its own branch, its own working directory, and zero interference from whatever is running next door. The Claude Code team has been calling it one of the biggest productivity unlocks in the tool, and after running three sessions in parallel for a week, that framing is about right, with one important footnote we'll get to.

This guide covers the actual mechanics: the flag, the subagent integration, the cleanup behavior, and the shared-state traps that worktrees don't solve. If you've already read our Claude Code subagents guide, this is the companion piece on the filesystem side of parallel work.

What a git worktree actually is

A git worktree is a separate working directory linked to the same repository. One .git directory, many checkouts. Each worktree has its own branch checked out, its own files on disk, and its own index. They share commit history and remotes, so pushing from one worktree updates the same remote as pushing from another.

The git command predates Claude Code by years. What's new is that Claude Code now creates and manages worktrees for you, scopes the agent session to that directory, and cleans up afterward if nothing changed. You don't have to know the git worktree add / git worktree remove dance to use it.

The --worktree flag

The simplest usage is a single flag when you launch Claude Code:

claude --worktree feature-auth

That creates .claude/worktrees/feature-auth/ as a new directory, checks out a branch named worktree-feature-auth, and scopes the entire Claude session to that directory. The short form is -w, which does the same thing. If you omit the name, Claude generates a random one.

There's also --tmux, which launches the worktree session in its own tmux pane. Useful when you want to keep one terminal per worktree without juggling windows manually.

From inside the worktree session, Claude sees only the worktree directory. It can't accidentally edit the file your other session is mid-way through. When the session commits, the commit lands on the worktree branch. When you push, it pushes the worktree branch to the same remote as your main checkout.

Running three sessions in parallel

The pattern that has been working well looks like this. Open three terminals. In each one, start a session with a different worktree name and a different task:

# terminal 1
claude -w "Add unit tests for the UserProfile component"

# terminal 2
claude -w "Fix the race condition in the data sync service"

# terminal 3
claude -w "Refactor the API client to use fetch instead of axios"

Three sessions. Three branches. Three directories under .claude/worktrees/. None of them can see or touch the others' files. You can review terminal 1's diff while terminal 2 is still working, then flip to terminal 3 to answer a question. You stop being a bottleneck and start being a reviewer.

The ceiling on this is you, not the tool. Two to four parallel sessions is where most people land. Past that, the review queue piles up faster than the agents finish, and you end up rubber-stamping or ignoring diffs you should be reading. The speedup becomes theoretical. Start with two.

Subagent isolation with isolation: worktree

Worktrees also work one level deeper, inside a single Claude session. When Claude dispatches a subagent via the Agent tool, you can tell that subagent to run in its own worktree by adding a line to the agent's frontmatter:

---
name: test-writer
description: Writes unit tests for a component you specify
isolation: worktree
---

With isolation: worktree, every invocation of that subagent creates a fresh worktree, runs the agent there, and either cleans up or reports the branch back to the parent session. This is what makes parallel subagent dispatch safe for tasks that touch overlapping files. Without isolation, two subagents editing the same file concurrently is a recipe for lost work.

The Claude Code power user guide covers agent frontmatter in depth. The short version: if a subagent writes to disk and might run in parallel with anything else, put isolation: worktree on it. If it's a read-only researcher that just greps and reports, skip the isolation. Creating a worktree has a small setup cost you don't want to pay for pure lookups.

Cleanup: what happens when the session ends

Cleanup depends on what the session did. If the worktree has no changes, no commits, no dirty state, Claude removes the worktree and its branch automatically when you exit. The .claude/worktrees/<name>/ directory disappears. The worktree-<name> branch is deleted. You end up with no trace except whatever was in the agent's history.

If the worktree has changes or commits, Claude prompts you. Keep the worktree so you can review or merge later, or discard it. Discarding deletes the branch and the directory. Keeping leaves both in place, and you're back to manual git worktree remove / git branch -D when you're done with them.

Two practical notes on cleanup. First, the auto-cleanup on empty worktrees is why you can use -w liberally for small exploratory tasks without polluting your repo. If the agent decides nothing useful came of it, the worktree evaporates. Second, the prompt on dirty worktrees means merges don't happen automatically. The agent does not push, does not merge to main, and does not open PRs unless you set that up yourself with a hook or a slash command.

The limit that worktrees don't solve

Here's the footnote. Git worktrees isolate files on disk. They do not isolate anything else. This matters more than you'd expect.

If two parallel sessions are both running migrations against your local Postgres, they're hitting the same schema. One agent's rollback is the other agent's broken test suite. If two sessions are both starting a dev server on port 3000, the second one crashes. If two sessions both read the same .env file and one agent writes a new value to it, the other sees that write whether it wanted to or not.

Practical mitigations, ordered by how much friction they add:

• Separate ports per worktree. If you launch dev servers, assign a port based on the worktree name or a per-directory .env override. PORT=3001 in one worktree, PORT=3002 in another.
• Separate databases per worktree. For migration-heavy work, give each worktree its own schema or its own Docker Compose project. A per-worktree docker-compose.<name>.yml with different volume names is a common pattern.
• Separate .env files. Keep a shared .env.shared with things that genuinely are shared, and per-worktree .env.local files for anything that isn't.
• Don't parallelize shared-state work. The honest answer for a lot of teams. If the task touches the database schema, run it alone. If it touches global config, run it alone. Reserve parallel sessions for feature work that's file-local.

This is where teams trip over the "10x productivity" claim. Worktrees give you 10x on independent feature work. They give you roughly 1x on work that fights over shared resources, and sometimes less than 1x if you have to debug a conflict you caused yourself.

Where worktrees don't belong

Worktrees are overhead. Not a lot, but not zero. Skip them when the overhead isn't worth it.

Small bugfixes that touch one file and resolve in five minutes don't need a worktree. Just edit the file. Quick lookups, "what does this function do," read-only exploration, none of this needs isolation. A session you're going to exit in two minutes shouldn't get a dedicated directory.

Same for work that has to see the rest of your in-progress changes. If you're halfway through a refactor in your main checkout and you want Claude to pick up from where you are, a worktree will give you a clean branch that doesn't have your uncommitted work. Stash or commit first, or skip the worktree and run Claude directly in your current checkout.

One more case where worktrees add friction: IDE integrations. If you've got a specific editor config, language server, or debugger attached to your main checkout, a fresh worktree won't inherit any of it. Symlinks to shared config files help, but for heavy IDE setups, some teams just run single-session and skip worktrees entirely.

Pairing with headless mode and CI/CD

Worktrees also pair well with Claude Code's headless mode. If you're running Claude in a CI pipeline, dispatching a worktree per job keeps parallel jobs from fighting over the same checkout. Our Claude Code CI/CD headless patterns guide covers the headless side in detail, and worktrees slot in cleanly: each CI job runs claude --worktree ci-$JOB_ID and cleans up when done, even on ephemeral runners.

The incident.io team wrote publicly about using this combination for batched migration work, and the shape of the setup is worth stealing: one parent orchestrator, one worktree per migration target, results rolled up into a single PR or set of PRs. The isolation is what lets the batch actually finish without a human babysitting every file conflict.

Desktop app users

If you're on the Claude Code desktop app, worktrees have a simpler entry point. Open the Code tab, enable worktree mode in settings, and every new session you start gets its own worktree automatically. No flag, no tmux integration to set up. The tradeoff is you lose the per-session naming, so you'll end up with auto-generated names like worktree-a7f3 in your branch list. Fine for short sessions, annoying for long-lived branches you want to name properly.

A reasonable starting setup

If you haven't used worktrees before, here's a minimal path in. Add this to your shell config:

alias cw='claude --worktree'

Now cw feature-x starts an isolated session. Use it for anything that's going to run longer than a minute or touches more than one file. Do the work, exit, let the auto-cleanup handle the empty case, keep and merge the dirty cases yourself.

Then, the next time you find yourself wanting a second Claude session on the same repo, open a second terminal and run another cw with a different name. That's it. The first time it works, it feels like a trick you've been missing.

For team setups where you're dispatching subagents programmatically, add isolation: worktree to any writer agent's frontmatter and leave it off for read-only ones. That single line is what turns "I can dispatch three subagents in parallel" from an aspiration into a thing that actually ships code.

What you're actually buying

Worktrees don't make Claude Code smarter. They don't reduce token usage. They don't improve the quality of any single session. What they do is remove the filesystem as a reason you can't run two sessions at once. That's a narrow win on paper and a large one in practice, because most developers weren't running parallel Claude sessions at all before this, simply because file conflicts made it more trouble than it was worth.

If you're still weighing Claude Code against other agent setups, our comparison of Claude Code, Cursor, and Copilot has more on where each fits. For parallel autonomous work specifically, worktree support is the piece that makes the "run three at once" workflow not just possible but actually pleasant.