# Parallel Claude Code Sessions with Git Worktrees

> Run several Claude Code sessions at once without edits colliding — the built-in claude --worktree flag, .worktreeinclude, subagent isolation, and cleanup.

Claude Code has worktrees built in: claude --worktree <name> starts the session in an isolated checkout under .claude/worktrees/, so two or three agents can work the same repo simultaneously without touching each other's files. Copy gitignored files like .env in via .worktreeinclude, isolate subagents the same way, and let Claude clean up unchanged worktrees automatically when you exit.

The first time you run two Claude Code sessions in one checkout, you learn why you shouldn't: both agents edit the same working tree, and one agent's refactor lands in the other's diff. The fix is the rule all parallel-agent workflows share — **one session per working tree** — and git worktrees are how you get cheap extra working trees over one repository. Claude Code has the whole pattern built in.

## The built-in way: `claude --worktree`

```bash
# terminal 1 — feature work
claude --worktree feature-auth

# terminal 2 — meanwhile, a bugfix
claude --worktree bugfix-123
```

Each command creates a fresh checkout under `.claude/worktrees/<name>`, on its own branch, and starts the session inside it. The two sessions now share git history but not files — work proceeds in true parallel, and each branch merges like any other. Three forms worth knowing:

- `claude --worktree` (no name) — auto-generates a name when you just need *a* sandbox.
- `claude --worktree "#1234"` — checks out PR #1234's head; ideal for "review and fix up this PR" tasks.
- `claude -w <name>` — the short flag.

By default worktrees branch from `origin/HEAD` — a clean, pushed state. If you want them to carry your local uncommitted work instead, set `"worktree": { "baseRef": "head" }` in [settings](/guides/configuration/claude-code-settings-permissions).

## The `.worktreeinclude` file

A fresh checkout contains tracked files only — which is correct for git and wrong for running your app: no `.env`, no local config. List what should follow you in a `.worktreeinclude` file at the repo root:

```text
.env
.env.local
config/secrets.json
```

It uses `.gitignore` syntax, and only files that are both **matched and gitignored** get copied (tracked files are already there). It applies to every worktree Claude Code creates — `--worktree` sessions and subagent worktrees alike.

## Isolating subagents, not just sessions

Parallelism inside one session hits the same collision problem: two subagents editing files simultaneously will trample each other. Same fix, one level down — give each subagent its own worktree:

- Ad hoc: tell Claude to **"use worktrees for your agents"** on a parallel task.
- Durable: set `isolation: worktree` in a [custom agent's](/guides/getting-started/writing-a-custom-agent) frontmatter.

Each subagent then works in a temporary worktree that's auto-removed if it made no changes — parallel edits without a shared mutable tree. This is the same isolation model the [multi-agent orchestration patterns](/guides/advanced/multi-agent-orchestration) assume.

## Sessions, memory, and what's shared

The sharing boundaries are worth getting straight once:

| Thing | Scope |
| --- | --- |
| Session history (`--continue`, `/resume`) | **Per directory** — each worktree has its own |
| Auto-memory | **Per repo** — all worktrees share it |
| `CLAUDE.md` | A file — travels with each checkout |
| Git history, remotes | Shared across all worktrees |
| Working files | Isolated per worktree |

Per-directory sessions are a feature: `--continue` in `feature-auth` picks up the feature conversation, not the bugfix one. And `/agent-view` gives you one screen to monitor parallel background sessions instead of alt-tabbing terminals.

## Cleanup

Worktrees are cheap to create and annoying to leak, so Claude Code manages the lifecycle: exit a session whose worktree has **no changes, no untracked files, no new commits**, and the worktree and its branch are deleted automatically. If there *is* work in it, you're asked to keep or delete. Two caveats: headless (`-p`) runs never auto-clean, and old subagent/background worktrees are only swept once they're past the `cleanupPeriodDays` window. The manual tools are standard git:

```bash
git worktree list
git worktree remove .claude/worktrees/feature-auth   # --force if it has changes
```

> [!TIP]
> Don't over-parallelize. Two or three concurrent sessions — a feature, a fix, a refactor — is where the workflow shines; ten is a review bottleneck wearing a productivity costume. Every parallel branch still funnels through the same merge queue and the same reviewer: you.

Worktrees solve *where* parallel agents work. For *how* to split the work itself — decomposition, handoffs, when parallel beats sequential — see [Building Multi-Step Agent Workflows](/guides/advanced/building-multi-step-workflows) and [Multi-Agent Orchestration](/guides/advanced/multi-agent-orchestration).

---

_Source: https://agentscamp.com/guides/advanced/parallel-claude-code-worktrees — Guide on AgentsCamp._