# Claude Code worktrees: run parallel sessions without collisions

Canonical URL: https://zero2vibecode.com/blog/claude-code-worktrees
Date: 2026-10-16
Tags: claude-code, git, agents

Two Claude Code sessions in one folder edit the same files and trip over each other. claude --worktree gives each session its own working copy on its own branch. Here is how to prepare a project, the trap with unpushed commits, and how to bring the work back.

You want one Claude Code session to tidy the documentation while another writes a missing test. Start both in the same project folder and they edit the same files, run commands in the same place and step on each other's work. The fix is not a smarter prompt. It is a second working folder.

This post is the first in a short series on the [Claude Code: Pro Level](https://zero2vibecode.com/learn/claude-code-pro) course. It walks through the lesson on [parallel sessions in worktrees](https://zero2vibecode.com/learn/claude-code-pro/4-1-worktree-sessions): what a worktree is, what to prepare before the first run, and the one surprise that catches almost everyone.

## What a worktree is

A worktree is another working folder of the same repository, checked out on its own branch. The folders share history, but each has its own files. Claude Code can create one for you and start a session inside it:

```bash
claude --worktree docs-pass
```

That command creates `.claude/worktrees/docs-pass/` on a new branch called `worktree-docs-pass` and opens a session there. The short form is `claude -w docs-pass`. The session's edit tools do not touch your main folder, and its commands do not run there.

One condition: you must have run plain `claude` in this repository at least once and accepted the folder trust prompt. If you have not, `claude --worktree` exits with an error.

## What the copies share, and what each keeps

The mental model is simple once you see it as a table:

| Shared by all worktrees | Each worktree has its own |
|---|---|
| commits | uncommitted edits |
| branches | installed dependencies (`node_modules`) |
| history | files git ignores, such as `.env` |

Every worktree is a fresh checkout from git. That has a practical consequence: the session in a new worktree has to install dependencies before it can run anything. And anything git ignores — your `.env`, for example — is simply not there.

## Two steps before your first parallel run

### Keep the worktrees folder out of git

Without this, the contents of every worktree show up in your main folder as untracked files:

```bash
echo '.claude/worktrees/' >> .gitignore
git add .gitignore && git commit -m "Ignore Claude Code worktrees"
git push
```

Ignore exactly `.claude/worktrees/`, not the whole `.claude/` folder. That folder also holds settings and skills you commit for your team.

### List the ignored files you actually need

If the project needs `.env` to run, put it in a `.worktreeinclude` file at the repository root. Every new worktree then gets a copy:

```bash
echo '.env' > .worktreeinclude
```

Keep that list short. Every worktree gets its own copy of every secret you name there.

## The trap: your fresh commit is missing

This is the part people lose an afternoon to. A new worktree does not branch off your local HEAD. It branches off **the main branch on the remote**. Commits you have not pushed, and work sitting on your feature branch, are not in it.

That is why the `.gitignore` step above ends with `git push`. If you really do need to start from your local state, add this to `.claude/settings.local.json`:

```json
{ "worktree": { "baseRef": "head" } }
```

If the repository has no remote at all, a worktree starts from your local HEAD anyway.

**Quick diagnosis.** 
A worktree session cannot see the commit you made an hour ago? Check whether you pushed it. Nine times out of ten, that is the whole story.

## Bringing the work back

Each session commits on its own branch. You do the merging, from the main folder, in a separate terminal:

```bash
git worktree list
git merge worktree-docs-pass
git merge worktree-test-pass
```

You merge it yourself because a session isolated in a worktree is not allowed to reach into the main folder: Claude Code blocks its git commands that point there. If both tasks changed the same lines, git stops at a conflict. Resolve it, or start `claude` in the main folder and ask for help with it.

Then type `/exit` in each session. If the worktree's branch has new commits, Claude Code asks whether to keep the worktree or remove it. Once you have merged, choose remove.

**Three things people regret.** 
Removing a worktree deletes its folder and its branch, including anything you have not merged — merge first, or choose keep. Answering "Yes, and don't ask again" to a shell command inside a worktree session usually saves that rule to the main folder's .claude/settings.local.json, where it applies to the whole repository even after the worktree is gone. And every extra session spends its own tokens, so give each one a single small task.

## When a worktree is the wrong tool

Worktrees solve one specific problem: two sessions that would otherwise edit the same folder at the same time. They do not make a task smaller or a plan clearer. If one session can do the job, one session is cheaper. If two tasks are going to rewrite the same lines anyway, you have only postponed the collision to merge time — split the work by files before you split it by folders.

Worktrees are also not the same as an agent team. The course's [agent teams lesson](https://zero2vibecode.com/learn/claude-code-pro/4-4-agent-teams) is explicit that teammates work in your shared working folder, not in separate worktrees, so two teammates editing one file will overwrite each other. Choosing between those patterns is the subject of the next post in this series.

## Frequently asked questions

**How is claude --worktree different from checking out another branch?**

Checking out a branch switches the one folder you have. A worktree gives you a second folder on its own branch, so two sessions can work at the same time without touching each other's files.

**Where does the worktree live and what is its branch called?**

claude --worktree docs-pass creates .claude/worktrees/docs-pass/ on a branch named worktree-docs-pass.

**Why is there no .env in my new worktree?**

Each worktree is a fresh checkout, and git does not track ignored files. List .env in a .worktreeinclude file at the repository root and it is copied into every new worktree.

**Can the worktree session merge its own branch into main?**

No. While a session is isolated in a worktree, Claude Code blocks its git commands that reach into the main folder. You merge from the main folder yourself.

## Try it yourself

The [worktree lesson](https://zero2vibecode.com/learn/claude-code-pro/4-1-worktree-sessions) has a practice terminal where you add the `.gitignore` rule, create `.worktreeinclude` and start a session in a `docs-pass` worktree. It runs in your browser, so you can rehearse the preparation before you try it on a real project.