Git worktree in Claude Code: parallel sessions

Practical information about working with Ailoot is in the documentation.

What is a git worktree in Claude Code#

Launching several agents in parallel in the same folder is the basic pain point of vibe-coding at 2026 speed. AI agents write code faster than a person can keep track of who is touching what. Without file isolation, launching two parallel Claude Code sessions in one directory ends with one session overwriting the other's work.

Git worktree solves this at the filesystem level. You have one main directory where you work. The command claude --worktree feature-auth creates the folder .claude/worktrees/feature-auth/ on a separate branch and starts Claude Code there. The files are isolated. Changes in one session are not visible to the other until you explicitly merge them.

The official Anthropic documentation puts it this way:

A self-check hint: if you've ever gotten a commit where half the files were someone else's work, you need a worktree.

How git worktree differs from a regular branch#

The standard Git flow: you're on the main branch and run git checkout feature-x—Git overwrites the working copy's files. A running npm run dev breaks because package.json changed underneath it. You stash your uncommitted changes and wait for the IDE to reindex. You switch back and everything gets overwritten again, so you have to stash and pop again.

Git worktree gives you another option: instead of switching one folder between branches, you create a second folder for another branch. The command git worktree add ../project-feature-x feature-x creates the directory ../project-feature-x/ with the files from branch feature-x. Your main stays in the original folder, and the dev server keeps running.

Previously, worktree mode in Claude Code had to be set up manually: git worktree add, then cd, then claude—and repeat in every terminal. The --worktree flag (also -w) does all three in one command.

Launch the first parallel session: the --worktree flag#

Minimal example. Open the first terminal at the project root:

claude --worktree feature-auth

Claude Code does three things:

1. Creates .claude/worktrees/feature-auth/ with a snapshot of origin/HEAD (usually your default branch).
2. Creates a new worktree-feature-auth branch.
3. Starts the session in this folder.

Open a second terminal in the same repository root folder:

claude --worktree bugfix-123

Done. Two Claude Code sessions, different files on disk, different Git branches. If you write authentication in the first and fix a failing test in the second, they physically can't get in each other's way.

If you don't want to type a name, Claude will come up with one:

claude --worktree
# → creates something like .claude/worktrees/bright-running-fox/

A tip for Git beginners: add .claude/worktrees/ to .gitignore. Otherwise, when you run git status in the main folder, you'll see the contents of all worktrees as untracked files:

# .gitignore
.claude/worktrees/

Pitfall to avoid: before the first --worktree launch in a new directory, enter it with a regular claude (without the flag) and accept the workspace trust dialog. If you don't, the flag fails with a “trust not accepted” error—including if you combine it with -p for headless mode.

Where worktrees live and how to find them#

The default location is fixed: .claude/worktrees/<value>/ at the repository root. If your project is in ~/dev/my-app/, the feature-auth worktree will be in ~/dev/my-app/.claude/worktrees/feature-auth/.

For nonstandard layouts (for example, if you want the worktree outside the repository), there is the WorktreeCreate hook—more on that below in the section about SVN and Mercurial.

Within one Claude session, you can switch to another existing worktree. Just say in the chat: “switch to .claude/worktrees/bugfix-123,” and Claude will call the EnterWorktree tool. The current folder will remain untouched—you can return the same way.

The standard Git command shows a list of all worktrees, including the main one and those created manually:

git worktree list

The output will look like this:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

Copying .env and secrets: the .worktreeinclude file#

When --worktree creates a new folder, it gets only what is committed to Git. .env with API keys and .env.local with local configuration are in .gitignore, so they aren't in the worktree. And the very first npm run dev fails with “MISSING DATABASE_URL.”

The homemade solution is to copy .env manually after every --worktree. It works once, then gets forgotten. Anthropic's solution is a .worktreeinclude file at the project root listing the Git-ignored files to copy automatically into every new worktree.

Create a .worktreeinclude file at the repository root:

.env
.env.local
config/secrets.json

The syntax is the same as .gitignore. You can use glob patterns:

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic gives a clear rule to prevent accidents:

In other words, you can't accidentally copy package.json through .worktreeinclude—it isn't in .gitignore. It's safe to put any patterns there.

The same .worktreeinclude works in three modes: manual --worktree, automatic worktrees for subagents (see below), and sessions from the Claude desktop app.

Worktree from a pull request for code review#

A standard code review scenario: a colleague sent a PR; you need to inspect the code, run tests, and leave a comment. With a regular git checkout pull/1234/head, you switch the working copy again and break your active session.

With the --worktree flag, this takes one command:

claude --worktree "#1234"

What happens: Claude Code runs git fetch origin pull/1234/head, creates a worktree in .claude/worktrees/pr-1234/, and checks out the PR branch. The session starts. You can immediately ask it to “read the diff, run the tests, and find logical errors”—while Claude works, your main session on main keeps running.

The alternative syntax is the full pull request URL:

claude --worktree https://github.com/OWNER/REPO/pull/1234

Use in a real project: pairing claude --worktree "#N" with your own code-reviewer subagent gives you an automatic review in a minute or two. Launch it in the background, continue your work in the main window, and return to the result through claude agents.

Base branch: worktree.baseRef for fresh or head#

The default setting is this: every new worktree starts from origin/HEAD. The advantage is a clean start that is guaranteed to match what CI will see. The drawback is that if you have uncommitted changes or several local commits beyond the remote on your current branch, they won't be included in the new worktree.

To start a worktree from your current local HEAD commit, add this to .claude/settings.json (or global settings):

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

Now claude --worktree experimental-feature starts from the current local HEAD. This is useful when your feature already has local commits that have not been pushed. It does not include tracked edits that are still uncommitted. If the subagent needs those edits, preserve and transfer the required changes explicitly, then inspect the destination diff; do not confuse that transfer with .worktreeinclude, which handles ignored local files.

The setting accepts exactly two values: "fresh" (= origin/HEAD) and "head" (= local HEAD). No arbitrary refs like "feature-branch" or a commit hash—this is a deliberate restriction to prevent a combinatorial explosion of options.

Isolate subagents automatically: isolation: worktree#

When you tell Claude “launch three subagents: one reads the database, the second looks at the API, and the third checks the tests,” all three work in your working copy by default. If even two of them write to the same file at the same time, there's a conflict. The solution is to give each one its own worktree automatically.

Method 1: ask verbally. Write to Claude in the conversation:

Use worktrees for your agents.

Claude will apply isolation to all subsequent subagents in this session.

Method 2: set it explicitly in the subagent itself. In the subagent file (for example, .claude/agents/code-reviewer.md), add a field to the frontmatter:

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

You're a meticulous reviewer. Read the diff and look for logic errors...

Now every launch of this subagent gets a temporary worktree in .claude/worktrees/. If the subagent didn't write anything, the folder is deleted automatically when it finishes. If there are uncommitted changes, Claude will ask whether to keep or remove them.

The base branch for subagent worktrees is the same as for --worktree: by default, origin/HEAD; with worktree.baseRef: head, local HEAD.

Decision matrix: worktree, /bg, subagent, or Agent View#

Typical combinations:

• “2 features in parallel, manually” — two terminals, each running claude --worktree. The simplest case.
• “Launch an overnight refactor; I'll close the app” — /bg + /goal with a completion condition. The session runs independently of your window.
• “One prompt, three parallel investigations” — three subagents with isolation: worktree. Each in its own sandbox.
• “What's running right now?” — claude agents. A dashboard of all sessions with “running,” “blocked,” and “done” filters.

5 pitfalls when working with worktrees#

1. Launched a worktree, .env is missing, nothing works. The most common problem. A worktree is a fresh checkout with no Git-ignored files. The solution is to add a .worktreeinclude file with .env* and the necessary local configs as soon as you set up worktree mode. Check that the file is at the repository root, not in .claude/.

2. You want to switch to the main branch, run cd to the root, and lose your uncommitted changes in the worktree. The root folder and worktree are two different working copies. You went back with cd; the changes in the worktree stayed in place—they didn't go anywhere. But if you got mixed up and ran git stash in the main folder, thinking you were in the worktree, the stash will be created on the main branch, not the one you expected.

3. Launched 5 parallel sessions and can't remember what each one is doing. Anthropic's documentation explicitly warns that most developers can't cognitively handle more than 2–3 sessions. A sign of overload is opening Agent View and not being able to immediately say what each agent is doing. Limit yourself to two concurrent sessions. If the task requires more, it should be orchestrated through /goal + subagents, not manually.

4. Worktrees from -p (headless) aren't cleaned up automatically. The command claude --worktree feature-x -p "do thing" doesn't show an interactive exit prompt, so there's no point when Claude asks “remove the worktree?” These worktrees accumulate. Clean them manually: git worktree remove .claude/worktrees/feature-x. Or use a cron script that removes anything older than 7 days.

5. Trust dialog in a new folder. If you open the repository for the first time and immediately run claude --worktree, the command will fail. Run claude without flags, accept workspace trust, and exit—then --worktree will work. This is intentional so Claude doesn't get access to someone else's project without the user's consent.

Cleanup: what gets deleted automatically#

The cleanup logic depends on what you've done in the worktree and how you started the session. Anthropic's documentation lists three scenarios:

Scenario 1: you entered, did nothing, and exited—the worktree was removed.

Scenario 2: you did some work and didn't commit it—Claude will ask “keep or remove?” when you exit. “Keep” saves the folder and branch for later. “Remove” deletes the directory together with uncommitted changes and new commits. This is destructive—don't click “remove” out of habit.

Scenario 3: you launched with -p (headless), and the command finished and exited. The worktree remains. Clean it manually:

git worktree remove .claude/worktrees/feature-x

Additionally, worktrees from subagents and /bg sessions are automatically removed by background cleanup if they are older than cleanupPeriodDays days (a setting, usually 30 days by default) and have no unsaved work. Worktrees from --worktree aren't touched by automatic cleanup—they're your responsibility.

Alternatives for SVN, Perforce, and Mercurial: the WorktreeCreate hook#

If the repository uses Subversion or Mercurial, the --worktree flag won't work directly. Anthropic provides an extension point through two hooks: WorktreeCreate (creates an isolated copy) and WorktreeRemove (removes it).

Example SVN hook from the official documentation:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

The hook reads the worktree name from stdin ({ "name": "feature-auth" }), runs svn checkout into a precomputed directory, and prints the path to stdout—Claude Code uses it as the working directory for the new session.

An important caveat: when using your own hook, .worktreeinclude isn't used. If you need .env or other Git-ignored files in the new folder, copy them within the hook script itself.

What's next: three adjacent parallelism mechanisms#

Worktree gives you file isolation. /bg gives you context isolation. Subagents give you task isolation. Each mechanism solves one problem on its own. Together, they provide a way to work on three to five parallel tasks without cognitive collapse. This is the skill set behind advanced vibe-coding in 2026.

This topic naturally continues into three related subjects: how to set up an autonomous agent using /goal and Agent View, how to build your own subagents for your tasks, and how to launch hundreds of agents through Dynamic Workflows.

Open Ailoot.