# Parallel sessions in worktrees

Course: Claude Code: Pro Level — https://zero2vibecode.com/learn/claude-code-pro
Canonical URL: https://zero2vibecode.com/learn/claude-code-pro/4-1-worktree-sessions
Verified against: Claude Code v2.1.292 (2026-10-15)
Last updated: 2026-10-15

claude --worktree starts a session in a separate working folder on its own branch. Two sessions each edit their own copy of the files, and the work comes back through git merge from the main folder. Prepare .gitignore, remember .worktreeinclude, and know which branch a worktree starts from.

You want one Claude session to fix the documentation while another adds a test at the same time. Start both in the same folder and they will edit the same files and get in each other's way. You need a second working folder.

## What a worktree is

A worktree is another working folder of the same repository, on its own branch. The folders share history, but each has its own files.

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

Claude Code creates the folder `.claude/worktrees/docs-pass/` on a new branch `worktree-docs-pass` and starts a session in it. The short form is `claude -w docs-pass`. That session's edit tools do not touch your main folder, and its commands do not run there or point git at it.

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

## What is shared and what is not

| 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. So the session in a second worktree will have to install dependencies first.

## Preparing the project

**1. Keep the worktrees folder out of git.** Otherwise their contents show up in the 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/`: that folder holds settings and skills you commit for the team.

**2. Put the ignored files you need in `.worktreeinclude`.** If the project needs `.env` to run, list it in a `.worktreeinclude` file at the repository root, and it is copied into every new worktree:

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

List only what is necessary: every worktree gets its own copy of every secret.

## Which branch a worktree starts from

A new worktree branches off **the main branch on the remote**, not your local HEAD. Unpushed commits and work from your feature branch will not be in it. That is why step 1 ended with `git push`.

If you need to start from your local HEAD, add this to `.claude/settings.local.json`:

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

Without a remote, a worktree starts from your local HEAD anyway.

## 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 yourself: while a session is isolated in a worktree, Claude Code blocks its git commands that reach into the main folder. 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.

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. After merging, choose remove.

**Careful.** 
Removing a worktree deletes its folder and branch along with everything you have not merged. Merge first, then remove — or choose keep. And remember: "Yes, and don't ask again" for a shell command in a worktree session is usually saved to the main folder's .claude/settings.local.json and applies across the whole repository, even after the worktree is gone. Several sessions at once also multiply token usage: give each one a single small task.

**Practice in the terminal.** Append .claude/worktrees/ to .gitignore, create .worktreeinclude with the line .env, and run claude --worktree docs-pass. In the practice terminal that is just a greeting — in a real project a .claude/worktrees/docs-pass/ folder appears on the worktree-docs-pass branch.