Atlas
TechnicalHow-to

Claude Code Worktrees: Run Parallel Sessions Safely

Run parallel Claude Code sessions in git worktrees: the --worktree flag, .worktreeinclude, base branch, subagent isolation, cleanup and pitfalls.

The short version

  • Run claude --worktree <name> in each terminal and every Claude Code session gets its own checkout and branch, so parallel edits cannot overwrite each other.
  • A worktree is a fresh checkout: install dependencies in it, and list gitignored files such as .env in a .worktreeinclude file so they are copied in.
  • New worktrees branch from the remote default branch unless you set worktree.baseRef to head, which carries your unpushed local work.
  • Worktrees isolate files only; they share the repository's .git directory, project-scope plugins and saved permission approvals with the main checkout.
  • An unnamed clean worktree is removed on exit; a named one prompts you first, and one with work in it asks you to keep or remove it. Non-interactive -p runs are never cleaned up automatically.
On this page
  1. The short version
  2. What is a git worktree, and why use one with Claude Code?
  3. How do I start Claude Code in a worktree?
  4. Why does my fresh worktree not run? Set up the environment
  5. Which branch does a new worktree start from?
  6. Can subagents get their own worktrees?
  7. What does Claude Code block inside a worktree?
  8. What do worktrees share with the main checkout?
  9. How does worktree cleanup work?
  10. A workable routine for two or three parallel tasks
  11. Conclusion
  12. Questions people ask

To run several Claude Code sessions on one repository without them overwriting each other, give each session its own git worktree. Start each one with claude --worktree <name>; Claude Code then creates a separate checkout on its own branch and works only there. This guide covers the setup, the files a fresh worktree lacks, how branches are chosen, how subagents can be isolated too, and how cleanup works.

Everything below comes from Anthropic's worktrees documentation and its common workflows page. Flags and behaviour change between Claude Code versions, so check claude --help and the docs for the version you run.

What is a git worktree, and why use one with Claude Code?

A git worktree is a separate working directory with its own files and branch that shares the repository's history and remote with your main checkout. If two sessions edit the same directory, one can change a file while the other is mid-task. With a worktree per session, each has its own copy of the files.

The docs list worktrees as one of several ways to run Claude in parallel, and they are specific about the scope: worktrees isolate file edits. Subagents split work up inside one session, and cross-session messaging lets sessions in different worktrees pass findings to each other. Agent teams, which coordinate several sessions automatically, are a separate feature. This article is about the isolation layer under them.

How do I start Claude Code in a worktree?

Pass --worktree (or -w) with a name:

bash
claude --worktree feature-auth

By default the worktree is created under .claude/worktrees/<name>/ at your repository root, on a new branch called worktree-<name>. Run the same command with a different name in a second terminal and you have a second isolated session. If you omit the name, Claude generates one such as bright-running-fox.

Requirements and details from the docs:

  • The repository needs at least one commit, because a worktree is created from an existing commit.
  • Interactive runs need workspace trust. If you have never run claude in the directory, run it once and accept the dialog, or --worktree exits with an error. Non-interactive -p runs skip that check.
  • Add .claude/worktrees/ to .gitignore so worktree contents do not show up as untracked files in the main checkout.
  • If a worktree with that name already exists, Claude Code opens it instead of creating a new one.
  • --worktree only works in a git repository, unless you configure WorktreeCreate and WorktreeRemove hooks for another version control system.

You can also ask Claude mid-session to "work in a worktree". It then uses its EnterWorktree tool. If the target path is outside .claude/worktrees/, Claude Code asks for your approval first.

Branch from a pull request

To start from a specific pull request or merge request, pass its number with a #, or its URL. Quote it so the shell does not read # as a comment:

bash
claude --worktree "#1234"

Claude Code fetches that change's head commit from origin and creates the worktree at .claude/worktrees/pr-<number>. The fetch never waits for input: if git or ssh would ask for a password, passphrase or new-host confirmation, it fails with an error instead. The docs suggest loading your key into ssh-agent and running git fetch once by hand first.

Why does my fresh worktree not run? Set up the environment

A worktree is a fresh checkout. Dependencies are not installed and untracked files are missing. Two fixes:

  1. Ask Claude to install dependencies in the worktree, or run your setup yourself in the directory under .claude/worktrees/.
  2. Add a .worktreeinclude file at the project root to copy gitignored files such as .env into every new worktree.

The file uses .gitignore syntax. Only files that match a pattern and are also gitignored are copied, so tracked files are never duplicated:

text
.env
.env.local
config/secrets.json

This applies to --worktree worktrees, subagent worktrees and desktop-app sessions. It does not apply if you replace creation with a WorktreeCreate hook; then you copy files in your own script.

One thing to decide on purpose: .worktreeinclude copies secrets into more places on disk. Keep the list short and only include what the session truly needs.

Which branch does a new worktree start from?

By default new worktrees branch from the repository's default branch on the remote, usually main. That is worktree.baseRef set to "fresh". If you want the worktree to carry your unpushed commits and feature-branch state, set it to "head" in settings:

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

You cannot set baseRef to a branch name. To start from a specific existing branch, create the worktree with git yourself:

bash
git worktree add ../project-bugfix fix-issue-456
cd ../project-bugfix
claude

With "fresh", Claude Code fetches the default branch if the repository has not been fetched in the last 24 hours, capped at five seconds, and falls back to the cached ref if the fetch fails. With no remote configured, or no cached origin/HEAD that it can fetch, it falls back to your local HEAD.

A reuse gotcha: with the default "fresh" base, reopening a worktree name can reset it to the default branch instead of continuing at its old tip. That happens only when the sandbox is not restricting file writes in your session, the worktree has no uncommitted or untracked files, it is still on its own branch, and it either has no commits of its own or its pull request was merged and the remote branch deleted. In every other case, including when baseRef is "head", it reopens at the old tip. If you use the sandbox with "fresh", run git fetch origin and pass a new name to start from the latest default branch.

Can subagents get their own worktrees?

Yes. Ask Claude to "use worktrees for your agents", or make it permanent for a custom subagent with isolation: worktree in its frontmatter. This file in .claude/agents/ always runs in its own worktree:

markdown
---
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. A worktree with changes stays until a periodic sweep can remove it without losing work. Subagent worktrees use the same base branch rule as --worktree.

Note one subtlety from the docs: a subagent in its own worktree takes its starting instruction files from your main conversation, not from the worktree. In the default location it also does not load the CLAUDE.md or .claude/rules/ at the worktree's root as it reads files there, even if those differ on the worktree's branch. If your branches change instruction files, do not assume the subagent sees them.

What does Claude Code block inside a worktree?

While a session is isolated in a worktree, Claude Code blocks four kinds of tool call:

  • File edits (Edit, Write, NotebookEdit) that target a path in the main checkout.
  • Commands whose working directory resolves to the main checkout, or cannot be verified to stay outside it.
  • Git redirects into the main checkout, through git -C, --git-dir, GIT_DIR, GIT_WORK_TREE, or a cd before git.
  • Command shapes where it cannot verify from the text that git stays inside the worktree, such as a computed command name. You cannot turn this check off.

The same enforcement covers subagents spawned from the isolated session. The docs are clear about the limit: these checks read the edit path, the directory and the command text. They do not track which files a shell command writes, so cp or a shell redirect into the main checkout is not refused by them. Such commands fall under your normal permissions and sandbox settings. Treat the checks as a guard against accidents, not a security boundary.

What do worktrees share with the main checkout?

Files and branch are separate. These are shared:

  • The .git directory. With the sandbox on, git commit works from the worktree root, but by default fails with an index.lock error if you run claude in a subdirectory of the worktree.
  • Plugins installed at project scope.
  • Permission approvals. Choosing "Yes, and don't ask again" for a Bash command in a worktree session saves the rule to the main checkout's .claude/settings.local.json. It then applies in every worktree of that repository and survives the worktree's removal. On Windows the rule stays with that worktree.
  • Untracked skills, agents and commands, when the worktree has no .claude/skills directory of its own.

Hooks have a trap too. After Claude enters a worktree, ${CLAUDE_PROJECT_DIR} still points at the project root where the session started. If a hook needs the worktree path, read the cwd field in the hook's input JSON.

The docs do not describe isolating databases, ports or other services, because worktrees only separate files. If two sessions run the same dev server or share one local database, plan for that separately.

How does worktree cleanup work?

When you exit an interactive worktree session, Claude Code checks for changed or untracked files, uncommitted submodule work and new commits:

  • Clean and unnamed: the worktree and its branch are removed automatically. A named session prompts you first.
  • Has work in it: you are asked to keep or remove. Keeping preserves the directory and branch; return with the claude --worktree <name> --resume command Claude Code prints. Removing deletes both, along with the work in them.
  • State cannot be verified: it prompts instead of removing.

Two cases catch teams out. Non-interactive -p runs have no exit prompt, so their worktrees are not cleaned up, and the lock Claude Code took stays until a later sweep releases it. Remove one with git worktree remove, running git worktree unlock first if git refuses. Subagent and background-session worktrees are removed by a periodic sweep once older than your cleanupPeriodDays setting, but never when they still hold work, never one belonging to a --worktree session you have not backgrounded, and never worktrees you made yourself with git worktree add.

Resuming works across all this: a session that ended inside a worktree without exiting it returns to that worktree on --resume or --continue.

A workable routine for two or three parallel tasks

  1. Add .claude/worktrees/ to .gitignore and write a .worktreeinclude with only the env files needed.
  2. Start each task with claude --worktree <short-task-name> in its own terminal. Name them: an unnamed clean worktree is deleted on exit, while a named one prompts you first.
  3. Have each session install dependencies and run its own tests inside its worktree.
  4. Pick tasks that touch different areas. Separate worktrees stop overwrites but do nothing about two branches changing the same lines; you still resolve that at merge time.
  5. Open a pull request per branch, review each, and merge through your normal CI. Exit each session and remove worktrees you no longer need.

Isolation is cheap to set up; the cost is usage. Several sessions draw on the same plan or token budget at once, so keep an eye on usage when you go beyond two or three.

Conclusion

Worktrees give each Claude Code session its own files and branch, which removes the most common failure of parallel work: two agents editing the same file. Set up .worktreeinclude, pick the right worktree.baseRef, remember that databases and ports are still shared, and clean up -p worktrees yourself. Merge conflicts, review and CI remain your job.

Questions people ask

How do I run multiple Claude Code sessions at once without conflicts?

Start each session with claude --worktree <name> in its own terminal. Each gets its own checkout under .claude/worktrees/<name>/ on a branch named worktree-<name>, so file edits do not collide.

Why are my .env files missing in a Claude Code worktree?

A worktree is a fresh checkout, so gitignored files are not copied. Add a .worktreeinclude file at the project root listing them, such as .env and .env.local; only files that match and are gitignored are copied.

Which branch does claude --worktree start from?

By default from the repository's default branch on the remote, usually main. Set worktree.baseRef to head in settings to start from your current local HEAD with unpushed commits. It cannot be set to a branch name; use git worktree add for that.

Does Claude Code delete worktrees automatically?

When an interactive session exits, a clean unnamed worktree and its branch are removed; a named session prompts you first, and one with work in it asks you to keep or remove it. Non-interactive -p runs are not cleaned up, and subagent worktrees are swept after cleanupPeriodDays unless they hold work.

Do worktrees stop all conflicts between parallel agents?

No. They isolate files only. Two branches can still change the same lines and conflict at merge, and sessions still share the .git directory, saved permission approvals and any local database or ports.

Sources

  1. Run parallel sessions with worktrees – Claude Code docs
  2. Common workflows – Claude Code docs

Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI. Claude and Claude Code are trademarks of Anthropic; Codex is a product of OpenAI.