Guides

    Claude Code Worktrees: Parallel Work in One Repo

    How to run Claude Code in git worktrees: the --worktree flag, plain git, .env files, merging three branches and cleanup. Git steps tested on 13-11-2026.

    November 13, 202613 min read
    Share:

    Published 13-11-2026. Last verified on 13-11-2026 against the Claude Code worktrees documentation and git 2.43.0, reviewed monthly.

    Quick answer: how do you use git worktrees with Claude Code?

    This guide to Claude Code worktrees is for developers and tech leads who want two to four Claude Code sessions working on one repository at the same time, without the sessions overwriting each other's files, and who then have to merge the results. Run claude --worktree feature-auth and Claude Code creates a separate checkout under .claude/worktrees/feature-auth on a new branch called worktree-feature-auth, then starts the session inside it. Open a second terminal, run the same command with another name and you have two isolated sessions on one repository. The hard part is not starting them. It is splitting the work so the branches merge cleanly, and in our own test two of three merges conflicted on files none of the tasks were about.

    How we tested this

    Our method in three lines: every command is either quoted from the official Claude Code or git documentation with the date we read it, or run by us with the output shown; we label which is which; and we say what we could not check. The gate for this page: a step that needs a live Claude Code session with model access is described from the documentation and marked "not tested by us", because this test run had no model access.

    What we did run, on 13-11-2026 with git 2.43.0: a test repository with three feature files, a README with a changelog and a package.json, three worktrees on three branches, one commit per branch that changed its own feature file plus the shared files, and three merges back into main. The numbers are in the merge section.

    The gate removed two claims we found in ranking articles. One says worktrees have no hard limit on the number of instances; we found no source for it. Another says WorktreeRemove hooks cannot block removal; the official worktrees page we read does not say that, so we leave it out.

    What is a git worktree, and why does it suit parallel agents?

    A git worktree is an extra working folder attached to the same repository, checked out on its own branch. All worktrees share one .git history, so a commit in one is instantly visible to the others, but the files on disk are separate. That is exactly what parallel agents need: each session edits its own copy, and nothing one agent writes can appear half-finished in another agent's folder.

    The alternative people try first is two sessions in one folder. That fails in a predictable way: session A rewrites a file while session B is halfway through reading it, and B's next edit is based on code that no longer exists. Cloning the repository twice works too, but every clone has its own history, its own fetch and its own disk footprint. In our test, each extra worktree took 32K on disk against 624K for the main checkout with its .git folder, because the history is not copied.

    We would use worktrees as soon as you want more than one session making changes at the same time. For one session plus a read-only research agent you do not need them. If you are still deciding whether to run agents in the background at all, our guide to Claude Code background agents and skills covers that choice, and the agents and orchestration collection has skills for coordinating several sessions.

    How does claude --worktree work?

    Pass --worktree or -w with a name and Claude Code creates the worktree and starts the session in it. The Claude Code worktrees documentation, read on 13-11-2026, gives these defaults: the folder is .claude/worktrees/<name>/ at your repository root, and the branch is worktree-<name>. Leave out the name and Claude generates one, such as bright-running-fox.

    The details that matter in daily use, all from that page:

    • The repository needs a commit. The common workflows page says a worktree is created from an existing commit. In an empty repository you get: Failed to resolve base branch "HEAD": git rev-parse failed.
    • The base is configurable. The setting worktree.baseRef takes "fresh" (the default) or "head". You cannot set a branch name there.
    • Resuming works by name. When you exit, Claude Code prints a claude --worktree <name> --resume command to come back to the same session.
    • Pull requests have a shortcut. claude --worktree "#1234" creates .claude/worktrees/pr-1234.
    • Subagents can get their own worktree. Add isolation: worktree to a custom subagent's frontmatter and each subagent run gets a temporary worktree, removed automatically when it finishes without changes. Our Claude Code subagents guide explains how to define those subagents.

    Two notes from us. Add .claude/worktrees/ to your .gitignore on day one, as the docs suggest, or a careless git add in the main checkout will try to add other sessions' folders. And give worktrees names that say what the session does, such as fix-billing-rounding, because those names end up as branch names in your pull requests.

    We have not run claude --worktree ourselves for this article; everything in this section is from the documentation as published on 13-11-2026.

    How do you set up worktrees with plain git?

    Use git worktree add with a path and a new branch, then start claude inside that folder. This is the route if your Claude Code version predates the flag, if you want the worktrees outside the repository folder or if other tools need the same setup.

    The script we ran on 13-11-2026:

    git worktree add -b feat-auth ../app-auth
    git worktree add -b feat-billing ../app-billing
    git worktree add -b feat-ui ../app-ui
    git worktree list
    

    Creating all three took 39 milliseconds, measured once on a small test repository. git worktree list then showed four folders, the main checkout plus three, each on its own branch at the same starting commit. In each folder you run claude as usual.

    One rule protects you from the most common mistake. When we tried to add a fourth worktree on a branch that was already checked out, git refused:

    fatal: 'feat-auth' is already used by worktree at '/tmp/wt/app-auth'
    

    The git worktree documentation states the same: add refuses a branch that is already checked out by another worktree unless you use --force. Our advice is never to use --force here. Two sessions on one branch is exactly the collision worktrees exist to prevent.

    The differences with the built-in flag are small but real. Plain git names the branch whatever you pass with -b, puts the folder wherever you point it and does nothing automatic on exit. Teams that script their environments will find helpers in our DevOps and cloud skills. Parallel Git Worktrees: Run Multiple Agents Without Clashes, $3, goes further by its listing: it manages isolated worktrees with port allocation, database namespacing and runtime isolation, which is what you need once each session also starts a dev server.

    How do you get .env and other ignored files into a worktree?

    Create a .worktreeinclude file in the project root and list the ignored files Claude Code should copy into each new worktree. A fresh worktree contains only tracked files, so your .env, local config and secrets are missing, and the first test run in the new session fails for a reason that has nothing to do with the code.

    The worktrees documentation describes the file as using .gitignore syntax, and copies only files that match a pattern and are also gitignored, so tracked files are never duplicated. A typical file:

    .env
    .env.local
    config/secrets.json
    

    It applies to claude --worktree, subagent worktrees and desktop sessions, and it is not processed when you replace the creation logic with a WorktreeCreate hook. With plain git worktree add nothing is copied; you copy the files yourself or script it.

    A word of caution from us: every worktree now holds a copy of your secrets. Keep the list to what tests need, prefer development keys over production keys and remember that cleanup removes the folder but not any key that was printed into a log. Our security skills collection has skills that check a repository for leaked keys before you push.

    What happened when we merged three branches back?

    Two of our three merges conflicted, and neither conflict was in the code the tasks were about. That is the single most useful result of our test.

    The setup: three branches, each changing its own feature file (auth.js, billing.js, ui.js). Like real agent sessions tend to do, each one also added a line to the changelog in README.md, and two of them bumped the version in package.json. Merging into main in order:

    MergeFeature fileREADME.mdpackage.jsonResult
    feat-authcleancleanuntouchedmerged without conflict
    feat-billingcleanconflictclean1 conflict
    feat-uicleanconflictconflict2 conflicts

    The first merge is always clean, because main has not moved yet. Every later merge collides on shared files that each session edited from the same starting point. The feature files themselves never conflicted.

    What we take from it, as rules for a team:

    1. Give shared files one owner. Changelog, version number, lockfile and route tables are edited by one session or by you after merging, never by every session.
    2. Merge in a fixed order and rebase the rest. After the first merge, rebase the remaining branches on main before merging them. Conflicts then show up in the worktree where the agent that made them can fix them.
    3. Review before you merge, not after. A conflict is easy; a clean merge of two changes that break each other is not.

    This was a git-level test with commits written by a script, not by Claude. We expect real sessions to touch more shared files, not fewer. For help on the merge step, our roundup of Git automation skills for Claude Code and the code quality and review collection cover review and merge helpers.

    How do you split the work so sessions do not collide?

    Split by files, not by features: each session should own a set of files that no other session writes to, and the brief for each session should say which. A feature split such as "auth" and "billing" sounds clean but both features often touch the same router, schema or config file.

    Our working pattern for three sessions:

    • Write the ownership into each brief. "You may edit src/billing and tests/billing. Do not touch package.json or README.md." Claude follows that kind of constraint well when it is explicit.
    • Keep one session for integration. The last step, wiring the pieces together and updating shared files, belongs to one session after the merges, or to you.
    • Cap it at three or four. Every extra session is another branch to review. Past four, we find the review becomes the bottleneck, not the agents.

    Two of our skills make this repeatable. Sub-Agent Task Briefs: Split Work Without Conflicts, $5, writes a self-contained brief per session with inputs, outputs, file ownership and a merge owner. Agent Orchestrator: Parallel Coding Agents is free and by its listing turns a large task into a task graph, runs Claude Code, Codex or Gemini CLI in parallel worktrees and merges in ranked order. For a team that wants fixed roles, Run a Team of Coding Agents at Once, $15, gives each agent a role, its own copy of the code and a merge order decided upfront. None of the three was run by us for this article.

    We sell skills that Claude Code, Cursor, Codex CLI and Copilot load through one connection to Agensi (see the MCP setup guide), and we name ours where they fit the step. No vendor paid to be listed.

    For the bigger picture of how several agents hand work to each other, read our multi-agent orchestration guide, and the workflow automation collection has skills for the repeatable parts.

    When are worktrees the wrong answer?

    Worktrees are the wrong answer when the sessions need the same running resources, when the tasks depend on each other or when the work is small. In those cases you pay the merge cost without the speed gain.

    Shared running services. Three worktrees each starting a dev server on port 3000 collide, as do three test suites writing to one local database. Worktrees isolate files, not ports or databases. Either give each session its own port and database name, or run only one session that needs them.

    Dependent tasks. If task B needs the result of task A, running them in parallel just means B guesses. Run A, merge, then start B.

    Small changes. For a fix that takes one session ten minutes, three worktrees cost more in setup and review than they save.

    Installs per folder. Each worktree needs its own node_modules or virtual environment, which takes time and disk the first time. Our 32K per worktree is before any dependency install.

    When the problem is flaky tests in one of those parallel runs rather than the setup itself, our testing and debugging collection is the faster route.

    How do you clean up worktrees?

    For sessions started with claude --worktree, Claude Code handles most of it: the documentation says a clean worktree from an unnamed session is removed with its branch automatically, a named session asks first and a worktree with changes prompts you to keep or remove it. Worktrees from claude -p runs are not cleaned up.

    For everything else, git does the work:

    git worktree remove ../app-auth
    git worktree prune -v
    

    remove only works on clean worktrees, with no untracked or modified files, unless you add --force, and the main worktree cannot be removed. prune deletes the bookkeeping for worktrees whose folders are already gone. In our test, removing three clean worktrees and pruning left the branches in place. That is deliberate: delete merged branches yourself with git branch -d once you are sure.

    Your next step

    Start with two sessions, not four: one on a task that owns its files completely, one on a second task with no shared files, and merge them in order before you add a third. Once that runs without surprises, write the ownership rules into your briefs and scale up. For more ways to structure repeat work in Claude Code, our guide to Claude Code workflows is the logical next read. Flags and defaults change between Claude Code versions, so check the worktrees documentation against your version.

    Written by Samuel Rose, Founder of Agensi. Next scheduled review: 13-12-2026.