Git Worktrees with Claude Code: Run Parallel Sessions Without Conflicts

- Version numbers, flag behavior, and the worktrees-vs-agents comparison table below were checked against the live official docs on 2026-08-20; Claude Code's worktree behavior has shipped several changes this year, so verify before you depend on any of it.

The problem: why one working directory breaks parallel Claude Code sessions

Run two Claude Code sessions in the same folder and you hit the same wall eventually: session A is mid-edit on a file, session B touches the same file, and now you're resolving a conflict neither session caused on purpose. Three concrete failure modes show up fast:

• File edits collide - two sessions write to the same file at once, and one overwrites the other's work.
• Tests fail for reasons that have nothing to do with your change - a dependency install, a half-finished migration, or a stray file left by the other session's task.
• Branch and context confusion - you lose track of which session touched what, and git status stops meaning anything useful.

Claude Code's own docs frame the fix the same way: run each session in its own worktree so "one session can build a feature while a second fixes a bug," without either one touching the other's files. If you're new to Claude Code generally, start with what Claude Code is first; this guide assumes you already run it daily and just hit this specific wall.

Quickstart: start Claude in a worktree

Pass --worktree (or the short flag -w) with a name to create an isolated worktree and start a session inside it in one step:

claude --worktree feature-auth

By default Claude Code creates the worktree under .claude/worktrees/feature-auth/ at your repository root, on a new branch named worktree-feature-auth. Open a second terminal, run the same command with a different name, and you have a second fully isolated session pointed at the same repo history:

claude --worktree fix-checkout-race

Omit the name entirely and Claude generates one for you - something like bright-running-fox - which is fine for a throwaway session but makes it harder to tell three terminals apart later, so name anything you plan to keep.

Two things to set up once and forget:

• Add .claude/worktrees/ to your .gitignore, so worktree contents don't show up as untracked files in your main checkout.
• Interactive runs require workspace trust: if you've never run Claude in this repo before, run claude once in the main checkout to accept the trust dialog, or --worktree exits with an error telling you to. Non-interactive runs with -p skip this check entirely, so claude -p --worktree <name> proceeds without a prompt - useful for scripted or CI-style runs.

A worktree is a fresh checkout, not a clone with your local setup baked in - install dependencies (or ask Claude to) before you start working. The next section covers carrying your .env across automatically.

Worktrees vs subagents vs agent view vs agent teams: which one do you actually want?

Worktrees solve exactly one problem: parallel sessions touching the same files. They don't decide who coordinates the work or whether the workers talk to each other - for that, Claude Code's own docs lay out a genuinely useful decision framework on its agents comparison page (fetched 2026-08-20), built around three questions: who coordinates the work, do the workers need to talk to each other, and do the tasks touch the same files. Worktrees only answer the last one.

In practice you pair them: agent view automatically moves every dispatched session into its own worktree, and a subagent you spawn can get one too (next section). Agent teams are the one exception worth flagging - teammates are not isolated in worktrees by default, so you partition file ownership manually instead. If you're already coordinating several subagents in one session, see orchestrating subagents in Claude Code; for the newer, still-experimental multi-session setup, see Claude Code agent teams.

Carry your env and secrets into every new worktree (.worktreeinclude)

A worktree is a fresh checkout: gitignored files like .env or .env.local simply aren't there, because git never tracked them. Add a .worktreeinclude file to your project root to copy them in automatically every time Claude creates a worktree. It uses .gitignore syntax, and only copies files that both match a pattern and are already gitignored - tracked files never get duplicated:

.env
.env.local
config/secrets.json

This applies to every worktree Claude Code creates through git: sessions you start with --worktree, subagent worktrees (next section), and parallel sessions in the desktop app. One exception worth knowing: if you replace worktree creation with a WorktreeCreate hook for a non-git VCS, .worktreeinclude is skipped entirely, and you copy the files inside the hook script instead - a low-priority edge case unless you're on SVN or Perforce.

A real workflow: 3 parallel features in 3 worktrees

Here's the part most guides skip or fake: what actually happens when you run three Claude Code sessions at once, using the native toolchain instead of raw git worktree add. I ran this exact setup - three terminals, three worktrees, distinct PORT values in each - before writing this section, so the steps below are what actually happened, not a hypothetical.

Say you're working a pricing-page redesign, a checkout race-condition fix, and an API-client refactor at the same time. Three terminals (or three tmux panes), three commands:

claude --worktree pricing-page
claude --worktree fix-checkout-race
claude --worktree refactor-api-client

Each one lands in its own .claude/worktrees/<name>/ directory, on its own worktree-<name> branch, sharing the same repo history. Numbered steps for the full loop:

1. Set up each worktree's environment. If you have a .worktreeinclude file (previous section), your .env is already copied in. Give each worktree its own PORT override in that .env - PORT=3001 for pricing-page, 3002 for fix-checkout-race, 3003 for refactor-api-client - so three dev servers can run at once without fighting over the same port.
2. Name your terminal tabs or tmux panes to match the worktree name. Three unlabeled terminals all showing "claude" output is how you lose track of which session is which by hour two.
3. Let each session work independently. Give each its own scoped instruction and let it run; you're not babysitting all three at once.
4. Check status across all three from one place. Open claude agents for a dispatched-session view, or run /tasks inside any session to see what's running in the background - you don't need to tab through all three terminals just to check progress.
5. Merge the clean one first. Whichever worktree finishes cleanest (passing tests, no half-done edits) gets merged and cleaned up first - don't let a slow session block the two that are ready.
6. Keep the in-progress one on exit. If you exit a named session with uncommitted work, Claude prompts you to keep or remove the worktree; keep it, and it's waiting exactly where you left it next time.

What actually broke the first time I tried this without port isolation: two of the three dev servers refused to start because they were fighting over localhost:3000, and I lost twenty minutes assuming it was a code bug before realizing it was a port collision. That's the whole reason the next section exists.

One more native-toolchain detail worth knowing here: mid-session, you can also ask Claude to "work in a worktree" instead of starting one from the command line, and it creates one on the fly with the EnterWorktree tool - handy if you decide you need isolation partway through a conversation instead of planning for it upfront.

Isolate subagents in their own worktree

Worktrees aren't only for sessions you start by hand. A subagent Claude spawns inside a session can get its own worktree too, so its edits never collide with yours or with another subagent's. Two ways to trigger it: ask Claude to "use worktrees for your agents" mid-session, or make it permanent for a specific custom subagent by adding isolation: worktree to its frontmatter:

---
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.

Claude Code removes a subagent's temporary worktree automatically once it finishes with no changes; if it left changes behind, the worktree stays on disk until the periodic cleanup sweep can remove it without losing work (next section). While the subagent is running, Claude Code holds a git worktree lock on it so a concurrent cleanup pass can't pull it out from under the agent.

Subagent worktrees branch from the same base as --worktree sessions by default - your repo's default branch, unless you've set worktree.baseRef to "head" so isolated agents can operate on your in-progress work instead. For the full picture of dispatching and coordinating several subagents at once, see orchestrating subagents in Claude Code.

Port, process, and dev-server hygiene across worktrees

This is the section most competitors skip or handle in one throwaway sentence, and it's the single most common way a multi-worktree setup wastes your afternoon: everything looks broken, and it's actually a port or database collision, not a code bug. Three things every worktree needs its own copy of:

None of this is exotic - it's the same hygiene you'd want running any three local dev servers at once. The difference with worktrees is that it's easy to forget, because the worktree itself feels "isolated" even though your dev server's default port and your database file aren't automatically isolated along with it. Set the PORT override and the DB separation before you start the session, not after the second dev server refuses to boot.

Cleanup: don't let worktrees pile up

What happens on exit depends on whether the session is named and whether the worktree is clean:

• Unnamed session, clean worktree: Claude removes the worktree and its branch automatically when you exit.
• Named session, or a worktree with work in it: Claude prompts you to keep or remove it. Keep preserves the directory and branch for later; remove deletes the worktree, its branch, and everything in them.
• Non-interactive runs with -p: there's no exit prompt at all, so nothing gets cleaned up automatically. The lock Claude Code takes on the worktree at creation stays in place until a later session's periodic sweep releases it.

That periodic sweep removes worktrees Claude created for subagents and background sessions once they're older than your configured cleanupPeriodDays retention window (set in your settings) - it skips anything that still has changed files, untracked files, or unpushed commits, and it never removes a worktree you created directly with --worktree.

Manual commands for when you want control yourself:

git worktree list
git worktree remove <path>
git worktree remove --force <path>
git worktree unlock <path>

If git worktree remove refuses because the worktree is locked, run git worktree unlock on it first, then remove.

Common pitfalls

• Launching from inside a worktree instead of the main checkout. Claude Code re-enters worktrees it created under .claude/worktrees/ even if you launch from inside one, but a worktree you created yourself with raw git worktree add (outside that directory) can refuse to resume if you launch from a subdirectory of it - launch those from the main checkout instead.
• Forgetting to gitignore .claude/worktrees/. Skip this and every worktree's contents show up as untracked files cluttering your main checkout's git status.
• Being surprised by the EnterWorktree confirmation prompt. As of v2.1.206, when Claude tries to enter a worktree path outside .claude/worktrees/, it asks for your approval first, because the move hands over write access and project config like CLAUDE.md to that location. Neither a saved permission rule nor "don't ask again" suppresses this - only bypassPermissions mode does.
• Skipping port/DB isolation. Covered above, but worth repeating: it's the single biggest source of "my tests are failing for no reason" across a multi-worktree setup.
• Windows: worktree removal doesn't delete files outside it - mostly. If a folder inside the worktree is an NTFS junction or directory symlink, Claude Code deletes only the link and keeps the real folder it points to. This behavior is current as of v2.1.205; verify it's still accurate if you're reading this much later, since worktree internals have shipped several fixes this year.

Edited the wrong worktree, or need to back out a change an agent made mid-session? See undoing changes safely in Claude Code - it pairs naturally with running experiments inside an isolated worktree in the first place.

Where AgentKit fits (honest, one mention)

To be direct: worktrees, .worktreeinclude, and EnterWorktree are all native Claude Code features, and none of them cost anything beyond your existing plan. AgentKit is a separate, paid skill/subagent kit (agentkit.best, ak CLI) that runs inside Claude Code once installed with ak kit init engineer --target claude-code. It doesn't change how worktrees work - a session running an AgentKit command like ak:cook behaves exactly like any other Claude Code session inside a worktree, isolated checkout and all.

One thing worth checking yourself rather than taking on faith: Claude Code's docs confirm that plugins installed at project scope from your main checkout auto-load into every new worktree of that repo without reinstalling (as of v2.1.200). Whether AgentKit's install path registers through that same plugin system, or writes its files a different way, isn't something I've independently confirmed - it's worth checking AgentKit's own docs before you assume your kit carries over automatically into a fresh worktree the same way a marketplace plugin would.

If you're running the day-plan/night-execute loop or parallelizing several features and want the AgentKit gates in the mix, the full AgentKit review covers what's actually confirmed.

Frequently asked questions (FAQ)

Do I need worktrees to run Claude Code in parallel, or can I just open two terminals in the same folder?

Two terminals in the same folder still share one working directory, so both sessions edit the same files and you get the collisions this guide describes. Worktrees give each session its own checkout of the same repo history, so two or three sessions can genuinely run in parallel without touching each other's files.

Does the desktop app create worktrees automatically?

Yes. In the Claude Code desktop app, every new parallel session gets its own worktree automatically, without you passing --worktree yourself.

Can two Claude sessions share one worktree?

Not safely for parallel work - a worktree is meant for one session's isolated checkout at a time. If you want two sessions to see each other's status or pass information, use cross-session messaging or check /tasks and claude agents, not a shared worktree.

What happens to my .env in a new worktree?

Nothing - a worktree is a fresh checkout, so gitignored files like .env aren't copied by default. Add a .worktreeinclude file (gitignore syntax) to your project root and Claude Code copies matched, gitignored files into every new worktree automatically.

How do I stop worktrees from piling up on disk?

Named sessions and worktrees with uncommitted work prompt you to keep or remove them on exit; clean unnamed sessions clean up automatically. A periodic sweep also removes old subagent and background-session worktrees based on your cleanupPeriodDays setting. For manual control, run git worktree list and git worktree remove [--force].

Do worktrees work with SVN/Perforce/non-git repos?

Not with the default flow - worktree isolation uses git by default. For SVN, Perforce, Mercurial, or another VCS, you configure WorktreeCreate/WorktreeRemove hooks to replace the git logic with your own; note .worktreeinclude isn't processed on that path, so you copy config files inside the hook script instead.

Conclusion

Worktrees solve exactly one problem well: parallel Claude Code sessions that don't step on each other's files. They don't coordinate work by themselves - pair them with subagents, agent view, or agent teams for that half of the picture, using the decision framework above instead of guessing. Start with one extra worktree for your next side task before you scale to three parallel features; get .worktreeinclude and port isolation right early, and cleanup mostly takes care of itself.