# Run Parallel Claude Code Sessions with Git Worktrees

> Start a second Claude Code session in its own git worktree with `claude --worktree`, keep .env files in it, and clean up when you're done. Copy-paste.

- Canonical: https://guides-ai.pages.dev/guides/claude-code-parallel-sessions-worktrees/
- Plate 04.06 · Topic: Workflows (https://guides-ai.pages.dev/topics/workflow/)
- Published: 06 Sept 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.pages.dev/

Two Claude Code sessions editing the same checkout will step on each other's files. A [git worktree](https://git-scm.com/docs/git-worktree) is a separate working directory on its own branch that shares the repository history — so one session can build a feature while another fixes a bug, and neither sees the other's edits. Claude Code creates and cleans these up for you.

## 1. Start Claude in a worktree

From the root of a repository that has at least one commit:

```bash
claude --worktree feature-auth
```

Creates `.claude/worktrees/feature-auth/` on a new branch `worktree-feature-auth` and starts Claude inside it. `-w` is the short flag; omit the name and Claude invents one like `bright-running-fox`.

The first interactive run in a directory needs workspace trust — if `--worktree` exits asking for it, run plain `claude` there once, accept the dialog, then retry.

## 2. Start a second session

In another terminal, same repository:

```bash
claude --worktree fix-login-bug
```

That's the whole trick: each terminal owns a worktree, each worktree owns a branch. While a session is isolated, Claude Code blocks edits and git commands that would reach back into the main checkout, and tells Claude how to rewrite a refused command.

Keep the worktree folders out of `git status`:

```bash
echo ".claude/worktrees/" >> .gitignore
```

## 3. Carry your `.env` into every worktree

A worktree is a fresh checkout, so gitignored files such as `.env` aren't there. List them in a `.worktreeinclude` file at the project root (gitignore syntax; only files that are also gitignored get copied):

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

Dependencies are not copied — ask Claude to run your install step, or run `npm install` / `uv sync` yourself inside `.claude/worktrees/<name>/`.

## 4. Branch from a pull request instead

Quote the argument so the shell doesn't read `#` as a comment:

```bash
claude --worktree "#1234"
```

Fetches that PR's head from `origin` and creates the worktree at `.claude/worktrees/pr-1234`. A GitHub PR URL or GitLab MR URL works too.

## 5. Clean up

When you exit an interactive worktree session, Claude checks for uncommitted work and new commits. A clean, unnamed session's worktree is removed automatically; if there is work in it, you're asked whether to keep or remove it. Non-interactive `-p` runs never prompt, so remove those yourself:

```bash
git worktree list
git worktree remove .claude/worktrees/feature-auth
```

`--force` removes a worktree that still has uncommitted changes; if git says the worktree is locked, run `git worktree unlock <path>` first.

## Worth knowing

- New worktrees branch from the repository's default branch (`main` on the remote). To branch from your current local `HEAD` instead — say, to isolate a subagent on in-progress work — set `{"worktree": {"baseRef": "head"}}` in `settings.json`.
- Reusing a name (`claude --worktree feature-auth` again) reopens the existing worktree rather than creating a new one.
- Subagents can get their own worktrees: add `isolation: worktree` to a custom agent's frontmatter in `.claude/agents/`.

---

Next: [use subagents](/guides/claude-code-subagents/) · [run Claude Code headless in a script or CI](/guides/claude-code-headless-ci/).