--- title: "Use Parallel Worktrees in Claude Code" description: "Parallel worktrees let two Claude Code sessions edit the same repo without colliding. Here is how to run two product explorations at once and compare them." canonical_url: "https://builderscamp.com/guides/tools/claude-code-worktrees-for-parallel-pm-work" date_published: "2026-09-18" date_modified: "2026-09-18" author: "Andre Albuquerque, Tiago Pedro da Costa" publisher: "Builders Camp" guide_class: "tools" --- # How to use parallel worktrees in Claude Code **TL;DR:** Running claude --worktree twice with different names gives you two isolated checkouts of the same repository, each on its own branch, so two explorations can touch the same files without colliding. The setup cost is real, because a worktree is a fresh checkout with no dependencies and no .env file. The payoff is a genuine side-by-side comparison instead of an argument about which approach would have been better. ## What problem does this actually solve for a product manager? The problem where you have two credible answers and no way to compare them without building one first and letting it poison your view of the other. Users abandon at the plan picker: is the fix fewer plans, or a calculator that shows what they would actually pay? You can reason about that for a week, or you can have both standing in front of you by Thursday afternoon. Parallel worktrees are what make the second option practical. Each worktree is a separate working directory on its own branch, sharing the same repository history, so two sessions can rewrite the same file at the same time and neither one sees the other's changes until you choose to look. The glossary entry on [parallel worktrees](https://builderscamp.com/guides/glossary/parallel-worktrees) covers the mechanism. This page runs it. ## How do you start two at once? One flag, twice, in two terminals. ```bash claude --worktree fewer-plans ``` ```bash claude --worktree price-calculator ``` Claude Code creates each worktree under `.claude/worktrees//` at your repository root, puts it on a new branch named `worktree-`, and starts the session there. By default each one branches from your repository's default branch on the remote, so both explorations start from the same clean baseline rather than from whatever half-finished state your main checkout is in. Setting `worktree.baseRef` to `head` in settings changes that when you deliberately want the worktree to carry your current work. Add `.claude/worktrees/` to `.gitignore` before you start, or every worktree you create shows up as untracked noise in the main checkout. You can also ask Claude to work in a worktree mid-session rather than deciding up front, and there is a third form worth knowing: passing a pull request number, quoted so your shell does not read it as a comment, creates the worktree from that change's head commit. That turns "can you look at what Marco proposed" into a one-line command instead of a branch-switching ritual. ## What breaks the first time? The app does not run. This surprises everyone once, and the reason is that a worktree is a fresh checkout: gitignored files are not there. No installed dependencies, no `.env`, no local database config. Dependencies you install in the worktree directory like any other checkout. The environment files are the part worth automating, with a `.worktreeinclude` file at your project root listing what to copy in: ```text .env .env.local config/secrets.json ``` It uses gitignore syntax, and only files that both match a pattern and are actually gitignored get copied, so tracked files are never duplicated. Write it once and every worktree Claude Code creates afterwards starts usable. One more first-time surprise: if your repository uses Git LFS installed with the `--local` flag, a new worktree contains pointer files rather than the real assets. Running `git lfs pull` inside the worktree fixes it. ## How do the two explorations stay apart? Claude Code enforces the boundary rather than trusting it. While a session is isolated in a worktree, four checks apply: an edit targeting a path in the main checkout is blocked, a shell command whose working directory resolves to the main checkout is blocked, a git command redirected back to the main checkout through `git -C`, `--git-dir` or a `cd` is blocked, and a command whose shape cannot be verified is refused with an explanation of how to rewrite it. That last one is the interesting one, because it means Claude Code refuses to guess. A clever one-liner that computes a command name at runtime gets rejected rather than run hopefully, and the agent is told to split it into plain separate commands. The same enforcement extends to any subagent spawned from an isolated session, which matters once you go past two terminals. A custom subagent with `isolation: worktree` in its front matter always runs in its own checkout, so a refactoring agent and a test-writing agent can work simultaneously without either one discovering the other's half-finished file. Claude Code removes those temporary worktrees automatically when the subagent finishes with nothing to keep. One setup detail catches people on a new machine: an interactive worktree session needs the directory to be trusted first. Run `claude` once in the repository and accept the trust dialog, otherwise the worktree flag exits with an error telling you to. Three things still cross the boundary on purpose: the repository's `.git` directory, so commits work normally from inside a worktree; project-scope plugins, so you do not reinstall them per worktree; and saved permission approvals, which are written to the main checkout's settings and therefore apply everywhere in the repository rather than dying when that worktree is removed. ## How do you finish? The comparison is the deliverable, so schedule it. Two prototypes that nobody sits down to compare produce the same outcome as one prototype and a longer meeting. Run each branch against the same three questions before you look at either one: what did this cost to build, what does it assume about the user that we have not checked, and what breaks if we are wrong. Writing those questions before the prototypes exist is what stops you picking the one that looks more finished, which is usually just the one whose scope was smaller. Then clean up. Exiting an interactive session checks the worktree for changed files, untracked files and new commits, and prompts you to keep or remove it when it finds any; a clean, unnamed session is removed automatically along with its branch. Non-interactive runs get no prompt, so those you remove yourself with `git worktree remove`, preceded by `git worktree unlock` if git refuses because the worktree is locked. Keep the branch of whichever exploration won. Delete the other one on purpose, because a dormant branch of an abandoned approach is the thing somebody resurrects in six months without knowing why it was dropped. ## What this costs you Your attention, and it is not a small bill. Two worktrees means two sessions, two sets of context and two threads of reasoning you are holding simultaneously, and you are the only merge point. Anyone who has run three parallel explorations knows the failure: you end up with three half-explored options and a weaker decision than one properly explored option would have produced. The honest boundary is two, and only when the branches are genuinely different answers to the same question. If they are the same answer at different fidelities, build the cheap one. If one depends on the result of the other, it is a sequence, not a parallel pair, and forcing it into two worktrees just hides the dependency. Builders Camp teaches both halves of this. Building with Claude Code covers parallel worktrees inside its Parallel Execution at Scale module, alongside multi-agent orchestration, background agents and the quality gates that make several concurrent workstreams safe to merge, across 1 week with 2 live sessions and 9 microlessons. Project Management for Product covers the discipline underneath, planning, dependency management and risk, for delivery-heavy product managers, and sits in the Product Delivery Specialist Track. ## The second worktree is a commitment device The real effect is not speed. It is that starting the second exploration forces you to write down, before either one exists, what would make you choose it. Teams that only ever build one option rarely state that criterion, because they never have to. Two branches on the same repository make the criterion unavoidable, and the criterion, not the code, is the thing you keep. [See the Building with Claude Code bootcamp](https://builderscamp.com/bootcamps/building-with-claude-code?utm_source=guide&utm_medium=organic&utm_campaign=claude-code-worktrees-for-parallel-pm-work) for the orchestration module, [Project Management for Product](https://builderscamp.com/bootcamps/project-management-for-product) for the delivery side, or [the Product Delivery Specialist Track](https://builderscamp.com/tracks/product-delivery) for the full sequence. For the coordination layer above a single pair of worktrees, see [multi-agent orchestration](https://builderscamp.com/guides/glossary/multi-agent-orchestration). ## Frequently asked questions ### What is the fastest way to start one? Run claude --worktree with a name. Claude Code creates the worktree under .claude/worktrees// at the repository root, on a new branch called worktree-, and starts the session there. Run the same command with a different name in a second terminal for a parallel session. ### Do I need to set anything up first? The repository needs at least one commit, because a worktree branches from an existing one. Add .claude/worktrees/ to .gitignore so worktree contents do not show up as untracked files in your main checkout. ### Why does the app not run in my new worktree? A worktree is a fresh checkout, so gitignored files are not there. Dependencies need installing in that directory, and files like .env are absent. Add a .worktreeinclude file at the project root listing the gitignored files to copy into every new worktree Claude Code creates. ### Can a session in a worktree accidentally edit my main checkout? Claude Code blocks it. While a session is isolated, edits targeting a path in the main checkout are refused, as are shell commands whose working directory resolves there and git commands redirected back with flags such as git -C or --git-dir. ### What do the two worktrees still share? The repository's .git directory, project-scope plugins, and saved permission approvals. Choosing yes and do not ask again in a worktree writes the rule to the main checkout's settings, so it applies across the repository rather than dying with that worktree. ### How do I clean up when I am done? Exiting an interactive session prompts you when the worktree still holds changes, untracked files or commits, and removes a clean unnamed one automatically. Anything left over is removed with git worktree remove. If git refuses because the worktree is locked, release that lock first and run the removal again. ### Is this the same as running two subagents? No. Subagents split work inside one session and share your attention. Worktrees isolate file edits between separate sessions. They combine: a custom subagent with isolation set to worktree runs in its own checkout, which is how parallel edits stop conflicting. ## Sources - [Claude Code docs: Run parallel sessions with worktrees](https://code.claude.com/docs/en/worktrees) - [Claude Code docs: Common workflows](https://code.claude.com/docs/en/common-workflows) - [Git documentation: git-worktree](https://git-scm.com/docs/git-worktree) ## How this guide was made Researched from Builders Camp's bootcamp, track and masterclass material and the sources listed on this page, drafted with AI, and fact-checked against every source cited.