Claude Code worktrees: run parallel sessions without stepping on each other

A git worktree is a second working folder for the same repository, on its own branch, so two Claude Code sessions can edit code at the same time without touching each other's files. Claude Code builds this in: run claude --worktree feature-auth (or -w) and it creates .claude/worktrees/feature-auth on a new branch, worktree-feature-auth, from your default branch, and asks whether to keep or remove it when you exit. Copy gitignored files such as .env into new worktrees with a .worktreeinclude file, and give subagents their own worktree with isolation: worktree. Boris Cherny, who created Claude Code, calls running 3 to 5 worktrees at once "the single biggest productivity unlock."

Key takeaways

• One command: claude --worktree <name> (or -w). Leave out the name and Claude picks one.
• Where: .claude/worktrees/<name>/, branch worktree-<name>; add .claude/worktrees/ to .gitignore.
• Setup per worktree: it's a fresh checkout, so install dependencies there; .worktreeinclude copies .env and other gitignored files.
• Cleanup: an untouched worktree is removed on exit; one with changes asks you to keep or remove it.
• Isolation ends at the merge: worktrees stop sessions overwriting each other's files, not merge conflicts later.

What is a git worktree?

An extra working directory attached to the same repository, checked out on its own branch, sharing the repository's history (git). Each Claude session edits its own copy of the files, so one session's half-finished change never breaks another's build. Git won't check out the same branch in two worktrees, which keeps them apart.

How do you use worktrees in Claude Code?

From Anthropic's worktrees guide (Anthropic):

• Start one: claude --worktree feature-auth creates .claude/worktrees/feature-auth/ on a new branch worktree-feature-auth and starts the session there. Run the same name again to reopen it.
• From a pull request: claude --worktree "#1234" branches from that pull request into .claude/worktrees/pr-1234.
• Mid-session: ask Claude to "work in a worktree," and it moves the session into one.
• Base branch: the remote default branch by default; set worktree.baseRef to head to branch from where you are instead.

The repository needs at least one commit, and the first run in a folder asks you to trust it.

When you exit, a worktree with no changes is removed, branch and all. One with work in it asks you to keep or remove it; keep it and Claude prints the command to come back, claude --worktree <name> --resume. Removing deletes the branch and its uncommitted work, so commit first.

How do you copy .env files into a worktree?

A new worktree contains only what's in git. Create a .worktreeinclude file at the project root, in .gitignore syntax, listing files to copy over, for example .env and .env.local; only files that match and are gitignored are copied. Then install dependencies: "ask Claude to install dependencies, or run your project's setup yourself in the worktree directory."

Two settings help with large projects: worktree.symlinkDirectories links folders such as node_modules instead of copying them, and worktree.sparsePaths checks out only part of a monorepo (Anthropic).

Subagents in their own worktree

Add isolation: worktree to a subagent's frontmatter in .claude/agents/, or ask Claude to "use worktrees for your agents," and each subagent works in a temporary worktree (Anthropic). A subagent that changed nothing has its worktree removed at once; one with changes is kept until a periodic cleanup, by default after 30 days, as long as nothing is uncommitted or unpushed. /batch splits a large change across 5 to 30 subagents, each in its own worktree.

Agent teams are different: their teammates share one checkout, and Anthropic's guide warns that "two teammates editing the same file leads to overwrites" (Claude Code agent teams).

Worktrees in the desktop app and VS Code

• Desktop app: in the Code tab, choose the worktree option next to the branch name when you start a session. Worktrees go in .claude/worktrees/ unless you change it in settings, and you remove one with the archive icon, or automatically when its pull request merges (Anthropic). Git must be installed.
• VS Code: the extension has no worktree button; run claude -w in the integrated terminal or ask Claude to work in a worktree.

Setting up worktrees by hand

git worktree add ../app-feature-a -b feature-a
cd ../app-feature-a && claude
git worktree list
git worktree remove ../app-feature-a

Use git worktree prune to clear records of folders you deleted by hand.

What goes wrong with parallel worktrees?

• Merge conflicts: two sessions changing the same files will collide when you merge. Split work by area, as you would between people.
• Ports and databases: two dev servers want the same port, and two sessions can migrate the same database. Give each worktree its own port and, if needed, its own database.
• Disk space: every worktree has its own dependencies unless you link them.
• Too many at once: you still review every branch. Cherny's team recommends 3 to 5 (X), and Anthropic's agent-teams guide suggests starting with 3 to 5 teammates.

More habits in Claude Code best practices.

Worktrees in Codex and Cursor

• Codex: in the ChatGPT desktop app, choose Worktree under the composer and pick a starting branch; Codex keeps the 15 most recent managed worktrees and also reads .worktreeinclude (OpenAI).
• Cursor: worktrees are built into the Agents Window, with /worktree and /best-of-n in the editor and setup scripts in .cursor/worktrees.json (Cursor).

Parallel agents for a whole team

Worktrees split one person's work across several sessions. In Poly (usepoly.co), a team works with Claude Code or Codex in a shared browser room; its multi-agent mode gives each member their own agent on their own branch, refreshed from the main branch before every turn and merged when ready, and everyone sees what each agent is doing. Free to start. What is Poly?