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

A worktree is a separate working directory linked to the same git repository, with its own branch checked out on disk. A branch alone doesn't give you a second directory — checking out a different branch in the same folder replaces the files that are there. A worktree adds an entirely new folder so multiple branches can be checked out and edited at the same time.

How do I create a worktree for a Claude Code session?

Run git worktree add ../myrepo-feature-x feature-x from inside the main repo, then cd into the new folder and launch Claude Code there. That session operates entirely inside the new worktree's files, isolated from the main directory and any other worktrees.

Can two worktrees check out the same branch at once?

No. Git blocks checking out the same branch in two worktrees simultaneously and returns an error rather than allowing it. Create a new branch per worktree if you need multiple parallel sessions.

Do worktrees share node_modules or build artifacts?

No. Only the git object database and history are shared. Dependencies, virtualenvs, and build outputs live on disk separately in each worktree, so each one needs its own install step and its own disk space.

How do I remove a worktree when I'm done with it?

Run git worktree remove <path> rather than deleting the folder manually — deleting by hand leaves a stale reference in git's internal tracking. If a worktree was already removed the wrong way, git worktree prune cleans up the leftover reference.

Should I use worktrees or subagents for parallel Claude Code work?

Use subagents when the problem is context window isolation within one session on one set of files. Use worktrees when the problem is filesystem collision — multiple sessions needing to edit the same repo's files at the same time. The two combine well: a subagent can operate inside its own worktree for full isolation.

Claude Code Worktrees: Parallel Agent Sessions Without Branch Conflicts (2026)

How to use git worktrees to run multiple Claude Code sessions on the same repo at once — separate branches, separate directories, zero collisions.

Run two Claude Code sessions on the same repo at the same time and you'll hit the same wall every time: they both want to touch the working directory, and whichever one finishes second stomps on the first. Branches don't fix this — checking out a different branch in the same folder still means only one branch is on disk at once. Worktrees fix it, because a worktree is a second working directory pointed at the same repo, with its own branch checked out, sharing the same underlying git history.

This is the pattern that makes it possible to point one agent at a bug fix and another at a feature, in parallel, without either one seeing the other's uncommitted changes. Here's how it actually works and where it fits next to subagents.

What a Worktree Actually Is

A normal git repo has one working directory and one .git folder. A worktree adds a second (or third, or tenth) working directory that shares the same .git object database but checks out a different branch. Nothing is duplicated except the files on disk for that branch — commits, refs, and history are all shared.

git worktree add ../myrepo-feature-x feature-x
cd ../myrepo-feature-x
claude

That's the whole setup. ../myrepo-feature-x is a full, independent checkout of feature-x. Edit files there and the main repo directory is untouched. Launch Claude Code inside it and that session only ever sees feature-x's state.

Why This Matters for Agent Sessions

Claude Code sessions are stateful — they read files, write files, and reason about what's currently on disk. Two sessions sharing one directory will read each other's in-progress edits as ground truth, which produces exactly the kind of confused, half-finished output you'd expect. Worktrees give each session its own filesystem reality while still operating on the same repo, same remote, same commit history underneath.

The practical pattern: spin up one worktree per independent task, launch a session in each, let them run in parallel, then merge each branch back once its session is done. No file collisions, no manual coordination, no one agent overwriting another's half-written function.

Managing Worktrees From Inside a Session

Rather than shelling out to git worktree add by hand every time, Claude Code sessions can enter and exit worktrees as a scoped action — the session moves its working context into an isolated worktree for a task, then exits back out when done. This matters most in autonomous or multi-phase workflows where a single session needs to isolate one part of the work (say, a risky refactor) from the rest of the conversation's working state, without spinning up a full separate session for it.

Common Gotchas

One branch, one worktree. Git refuses to check out the same branch in two worktrees simultaneously — you'll get an error, not silent corruption. Use a new branch per worktree.
Dependencies aren't shared. node_modules, virtualenvs, and build artifacts live on disk per worktree, not in the shared .git database. Budget the install time and disk space for each one you spin up.
Orphaned worktrees pile up. Deleting the folder by hand doesn't clean up git's internal reference to it. Run git worktree remove ../myrepo-feature-x so the repo doesn't accumulate stale entries. git worktree prune cleans up ones already deleted the wrong way.
Disk usage adds up fast. Each worktree is a full checkout. Ten parallel worktrees on a large monorepo is ten full copies of the working tree — plan storage accordingly, or keep parallel worktree counts modest.

Worktrees vs. Subagents

These solve different problems and stack well together. A subagent isolates a task's context window inside one session, on one filesystem state. A worktree isolates the filesystem state itself, letting entirely separate sessions — potentially separate agents, separate terminals, separate machines — work on the same repo without collision. Use subagents when the problem is context pollution. Use worktrees when the problem is two sessions needing to edit the same files at the same time.

When to Reach for This

Worktrees earn their keep in a handful of recurring situations: running a fleet of agents against independent tickets in the same repo, testing two competing implementations side by side without stashing and restashing, or handling an urgent hotfix without disturbing a feature branch that's mid-flight in another session. If parallel work on one repo is a one-off, a second full clone works fine. If it's a repeated pattern, worktrees are faster to set up and lighter on disk because they share history instead of duplicating it.