lockstep
5 min readNaman Jain

Claude Code worktrees: run parallel sessions safely

Run parallel Claude Code sessions with git worktrees: claude -w, where worktrees live, .worktreeinclude, subagent isolation, cleanup, and what they share.

Two Claude Code sessions in one checkout is a race. One is refactoring the auth module while the other fixes a bug in the same file, and whichever writes last wins. Git worktrees fix that: each session gets its own working directory and branch, sharing the same repository history.

This guide covers the worktree workflow in Claude Code, from Anthropic's worktrees documentation, checked on 16 November 2026.

Start a session in a worktree

claude --worktree feature-auth

Or the short form, claude -w feature-auth. Claude Code creates a worktree at .claude/worktrees/feature-auth/ on a new branch, worktree-feature-auth, and starts the session there. Run the same command with another name in a second terminal for a second isolated session. Leave out the name and Claude picks one.

Two setup steps:

  • Ignore the folder. Add .claude/worktrees/ to .gitignore, so worktree contents don't appear as untracked files in your main checkout.
  • Trust the directory once. Interactive worktree sessions need workspace trust, so run claude once in the repository first if you never have.

You can also ask Claude mid-session to "work in a worktree," and it creates one for you.

Set up the environment

A worktree is a fresh checkout. Gitignored files like .env aren't there and dependencies aren't installed. Two fixes:

Copy small gitignored files with a .worktreeinclude at the project root. It uses .gitignore syntax, and only files that match and are gitignored get copied:

.env
.env.local
config/dev-credentials.json

Install dependencies by putting the install command in CLAUDE.md, so Claude runs it when it starts in a new checkout. Don't put node_modules in .worktreeinclude: it copies rather than links, which means a full copy per worktree. For large directories, Anthropic's best practices point to the worktree.symlinkDirectories setting.

Choose what the worktree branches from

New worktrees branch from your repository's default branch on the remote, so they start clean. To carry your current, unpushed work into new worktrees instead, set worktree.baseRef to "head" in settings:

{
  "worktree": {
    "baseRef": "head"
  }
}

To start from a pull request, pass its number or URL:

claude --worktree "#1234"

Claude Code fetches that pull request's head commit from origin and creates .claude/worktrees/pr-1234.

Give subagents their own worktrees

Subagents can work in separate worktrees, so parallel edits don't collide. Ask Claude to use worktrees for its agents, or make it permanent for a custom subagent:

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

Apply the requested refactor across every affected file, then run the tests and report the results.

Each subagent gets a temporary worktree, removed automatically when it finishes without changes. More on subagents in Claude Code subagents: 5 examples.

How isolation is enforced

While a session is in a worktree, Claude Code blocks tool calls that would reach into the main checkout:

  • File edits that target a path in the main checkout.
  • Commands whose working directory is the main checkout.
  • Git commands redirected into the main checkout, through git -C, --git-dir, or similar.
  • Commands whose git usage it can't verify from the command text.

These checks read paths, directories, and command text. They don't track every file a shell command writes, so a cp into the main checkout falls under your normal permission and sandbox settings instead.

What worktrees share

A worktree has its own files and branch, but some things carry across:

SharedDetail
Git historyWorktrees use the main repository's .git directory
Project pluginsInstalled at project scope in the main checkout, they load in worktrees too
Permission approvals"Don't ask again" in a worktree saves to the main checkout's settings
Untracked skills and agentsIf the worktree has no .claude/skills, the main checkout's load instead
Auto memoryAll worktrees of one repository share one auto memory directory

Cleanup

When you exit an interactive worktree session:

  • A clean, unnamed worktree is removed automatically, along with its branch.
  • A worktree with changes or new commits prompts you to keep or remove it. Keep it, and Claude Code prints the command to resume later.
  • A named session's worktree prompts you first.

Worktrees from claude -p runs have no exit prompt, so remove them yourself with git worktree remove, unlocking first with git worktree unlock if needed.

When parallel sessions still collide

Worktrees stop sessions from overwriting each other's files. They don't stop two sessions from making contradictory choices. One session renames an API field while another builds a client against the old name; both branches merge cleanly, and the product is broken. The fix is a decision both sessions see before they start, not a better merge.

Where Lockstep fits

Lockstep briefs every Claude Code session on the team's approved decisions at session start, so parallel sessions in different worktrees build against the same rules. Decisions are captured from PRDs, Slack, and pull requests, become binding when their owner approves them, and, when a session changes a shared API surface, Lockstep can route that change to the other services that depend on it. See two AI agents, one codebase.

Session briefings work with Claude Code today. See how it works.

Sources checked 16 November 2026

For the practices around unattended and parallel runs, see Claude Code best practices. For agent teams versus subagents, see Claude Code subagents: 5 examples. For teams of coordinated sessions, see Claude Code agent teams. To pick a session back up later, see how to resume a Claude Code session. For repository layout and agents, see monorepo vs polyrepo.

Frequently asked questions

How do I run Claude Code in a worktree?
Run claude --worktree <name>, or claude -w <name>. Claude Code creates a worktree under .claude/worktrees/<name>/ at the repository root on a new branch named worktree-<name>, and starts the session there. Run it again with another name in a second terminal for a parallel session.
Where does Claude Code put worktrees?
Under .claude/worktrees/ at your repository root. Add .claude/worktrees/ to .gitignore so their contents don't show as untracked files in your main checkout.
How do I get my .env file into a Claude Code worktree?
Add a .worktreeinclude file to the project root, using .gitignore syntax, listing files like .env and .env.local. Claude Code copies matching gitignored files into each worktree it creates. Keep it to small files, because it copies rather than links.
Do Claude Code worktrees get cleaned up?
When you exit an interactive worktree session, Claude Code removes a clean, unnamed worktree and its branch automatically, and asks before removing one that has changes or belongs to a named session. Worktrees from claude -p runs aren't cleaned up; remove them with git worktree remove.
Can subagents use worktrees?
Yes. Ask Claude to use worktrees for its agents, or add isolation: worktree to a custom subagent's frontmatter. Each subagent gets a temporary worktree that is removed when it finishes without changes.

Keep reading