How Do You Run Claude Code in a Git Worktree?

How Do You Run Claude Code in a Git Worktree?

Two agents editing one checkout is the fastest way to lose an afternoon. One rewrites a file the other is halfway through reasoning about, and neither notices until the tests contradict both of them.

Git has had an answer to this since long before coding agents existed, and Claude Code now has a flag that reaches for it directly.

The mechanics are documented in detail. The part that trips people up is not how to create a worktree but what it quietly keeps sharing with the checkout you started from.

That sharing list is published for one surface and left unstated for the other, which is the single most useful thing to know before you run the command.

Everything below comes from Anthropic's and Git's own documentation, with the gaps named where they exist.

How do you run Claude Code in a git worktree?

Pass --worktree with a name, or its short form -w. Claude Code creates an isolated worktree under .claude/worktrees/<name>/ at your repository root, puts it on a new branch called worktree-<name>, and starts the session there. Omit the name and Claude Code generates one.

Run the same command with a different name in a second terminal and you have two sessions on two branches in two directories, sharing one repository and colliding over nothing.

The documentation describes the point of it plainly: each worktree is "a separate checkout on its own branch, created from an existing commit". That last clause is a real constraint.

The repository needs at least one commit, and a fresh git init with nothing committed fails with an error about being unable to resolve the base branch HEAD.

Shipping faster than your analytics can keep up? Get a free SEO audit at seo-stuff.com/free-audit and see what the traffic is doing.

What a git worktree actually is

A worktree is a second working directory attached to one repository. Git's own description is that the new worktree is linked to the current repository and shares everything except per-worktree files such as HEAD and the index.

That sentence is the whole model. Two directories, two checked-out branches, one object store and one set of refs.

What gets shared

Refs are shared: in Git's words, "all refs starting with refs/ are shared", with narrow exceptions for bisect, worktree-scoped and rewritten refs. A branch you create in one worktree exists in the other immediately.

Configuration is shared too. Git states that by default the repository config file is shared across all worktrees, so remotes, aliases and hooks configured at repository level apply everywhere.

What stays per-worktree

HEAD, the index, and the working files themselves. Each worktree has its own staged changes and its own uncommitted edits, which is exactly the isolation you want when two agents are working at once.

The refusal that saves you

Git will not let two worktrees check out the same branch. add refuses when the target is a branch already checked out elsewhere, and only --force overrides it.

How to start a worktree session, step by step

• Confirm the repository has at least one commit. An empty repository cannot be the base for a worktree.
• Run claude --worktree <name> from the repository. Add --tmux if you want a tmux session for it; that flag requires --worktree.
• Approve workspace trust if prompted. Interactive runs require it. Runs started with -p skip the check entirely.
• Initialise the development environment inside the new directory. Dependencies are not installed for you, because the working files are a fresh checkout.
• Work as normal. Git writes go to the shared repository, so commits are visible from the main checkout straight away.
• Exit. Claude Code prints the exact command to come back, in the form claude --worktree <name> --resume.

To branch a worktree off a pull request instead of a commit, pass #<number>, a GitHub pull request URL, or a GitLab merge request URL.

Claude Code fetches that pull or merge request from origin and branches the worktree from it, which turns reviewing someone else's branch into a one-line command.

By default a worktree branches from your default branch rather than from whatever you currently have checked out. Setting worktree.baseRef to head in settings changes that to branch from your current work; fresh is the default.

Cleaning up

Cleanup depends on how you started. An unnamed session with no changes has its worktree and branch removed automatically on exit. A named session prompts first, and any worktree holding work asks whether to keep or remove it.

Non-interactive runs are the exception worth memorising: with -p there is no exit prompt, so Claude Code does not clean up their worktrees, and the lock taken at creation stays in place.

For anything stranded, claude rm accepts --discard-unpushed and --force-remove-worktree with a worktree ID.

Manual management still works throughout. git worktree list, git worktree remove and git worktree prune behave as they always have, and Git is strict about two of them: only clean worktrees can be removed without --force, and "The main worktree cannot be removed."

Your deploy pipeline is isolated. Is your reporting? Claim your free audit at seo-stuff.com/free-audit.

What the worktree shares with your main checkout

This is the section that decides whether a worktree session behaves the way you expect, and it is more surprising than the Git-level sharing.

The .git directory is shared, so every commit, branch and tag lands in the main repository. Project-scope plugins load inside worktrees from version 2.1.200 onwards.

Permission approvals leak outward by design. Choosing to stop being asked about a Bash command inside a worktree writes the rule into the main checkout's .claude/settings.local.json, and that rule survives the worktree's removal. A throwaway directory can leave a permanent permission behind.

Untracked project skills, agents and commands fall back to the main checkout when the worktree's root has none of its own.

Desktop and CLI are documented differently

On the desktop app, Anthropic is explicit: project configuration including settings, hooks, skills, agents, commands and .mcp.json servers is read from the main checkout's root rather than from the worktree.

CLAUDE.md files and .claude/rules/ are the stated exception and still load from the worktree.

Local settings follow the same shape. In a worktree, Claude Code uses the local settings file at the main checkout's root.

For the CLI path, none of this is stated. That gap is covered below, and it matters more than it sounds.

Subagents and hooks

A subagent running in its own worktree "takes the instruction files it starts with from your main conversation, not from its worktree". Its context comes from where it was spawned, not from where it is working.

Hooks split the difference. The working directory passed to a hook follows the worktree, while ${CLAUDE_PROJECT_DIR} "still points at the project root where the session started". A hook that assumes those are the same will write to the wrong place.

Session transcripts follow the worktree: Claude Code records the session under the session's new working directory. Resuming by session ID searches the current project directory and its worktrees first, then every other project on the machine.

When a worktree is the right tool

Reach for one when two pieces of work must not touch each other. A long refactor in one directory while a hotfix goes out from another.

A risky migration you may want to abandon wholesale. An agent let loose on a large change while you keep working.

Subagent isolation is the other good fit. Setting isolation: worktree in a subagent's frontmatter gives it a temporary worktree and an isolated copy of the repository, branched by default from your default branch rather than from the parent session's HEAD. A subagent that changes nothing has its worktree cleaned up automatically.

Limitations and where the docs go quiet

Git calls the foundation experimental. Git's own manual page, in its BUGS section, says "Multiple checkout in general is still experimental", adds that submodule support is incomplete, and advises against multiple checkouts of a superproject. Every agent workflow built on worktrees inherits that caveat.

The CLI sharing rules are not published. Anthropic spells out what comes from the main checkout on the desktop app, and spells out the local settings behaviour. For a CLI --worktree session it never says whether committed .claude/settings.json, .mcp.json, hooks or CLAUDE.md are read from the worktree or from the main checkout. A team wanting to know whether its shared MCP configuration applies inside a CLI worktree has no documented answer.

One page contradicts another on subagent isolation. The worktrees documentation says a subagent configured with worktree isolation in its frontmatter always runs in its own worktree. The subagents page says that with agent teams enabled, a named subagent launches as a teammate instead, that "An isolation value in the subagent's frontmatter doesn't prevent it", and that the teammate then runs in the main session's working directory. Both are first-party. The word "always" does not survive the second page, and the practical consequence is a subagent you believed was isolated editing your working directory.

Isolation is enforced against Git, not against the filesystem. A command that writes into the main checkout without going through Git, such as a copy or a shell redirect, is not refused by the isolation checks.

The sandbox has needed repeated fixing here. Recent changelog entries record a sandbox escape when creating a worktree, sandbox protections failing to apply to a worktree entered by a resumed or continued -p run, and a subagent's worktree being removed while a background subagent was still working in it. All fixed, and all pointing at the same seam.

Shared runtime resources are unaddressed. Nothing in the documentation covers port collisions, a shared local database, or duplicated dependency installs across parallel worktrees, beyond telling you to initialise the environment. In practice this is the first thing two parallel sessions fight over.

Measuring what the work actually moved? Start with a free audit at seo-stuff.com/free-audit.

Worktrees versus the alternatives

• A branch plus stash. Free, instant, and fine for one task at a time. It cannot give two agents two directories, which is the entire reason worktrees exist.
• A second clone. Full isolation including config and refs, at the cost of disk space, a second fetch, and branches that do not appear in your main repository until you push. Worktrees win on everything except isolation completeness.
• Background agents and teammates. Better when you want many sessions monitored from one screen rather than scattered across terminals. Note the agent-teams interaction above before relying on frontmatter isolation.

For most teams the useful pattern is a worktree per pull request under review, a worktree for anything an agent runs unattended, and plain branches for everything else.

Two branches, one set of numbers. Get a free SEO audit at seo-stuff.com/free-audit and see which work actually moved traffic.

Final Thoughts

Claude Code's worktree support is real, documented and more capable than a thin wrapper over git worktree: a dedicated flag, pull-request branching, a configurable base ref, hooks that can replace the creation logic outright, and automatic cleanup that knows the difference between a named session and a throwaway.

What it is not is complete isolation. The repository is shared, permission approvals written inside a worktree outlive it, the desktop app reads most project configuration from the main checkout, the equivalent CLI behaviour is undocumented, and one Anthropic page's claim that frontmatter isolation always applies is contradicted by another once agent teams are in play.

Use the flag, keep worktrees short-lived, and treat anything you configure inside one as though it might escape, because some of it does.

If you are running sessions you are not sitting in front of, our guide to Claude Code remote control covers the flag that gives each on-demand session a worktree of its own.