# Claude Code Parallel workspaces with worktrees

> Claude Code: Worktree startup, base branches, PR worktrees, local file copying, subagent isolation, cleanup, and non-Git hooks.

URL: https://docs.passion8.cc/en/docs/claude-code/worktrees
Language: en
Publisher: Passion8

A Git worktree is another working directory sharing repository history and remotes. Claude Code uses it to isolate parallel sessions so feature and bug-fix edits do not collide in one checkout.




Worktrees isolate file changes. See [Subagents](https://docs.passion8.cc/en/docs/claude-code/subagents) for delegation and [Sessions](https://docs.passion8.cc/en/docs/claude-code/sessions) for naming/resumption.




## When to use one

| Scenario | Recommendation |
| --- | --- |
| Two sessions editing one repository | Give each a worktree |
| Start clean from remote default branch | Default --worktree name |
| Subagent may edit | isolation: worktree |
| Local unpushed foundation commits | worktree.baseRef: head |
| Need ignored local configuration | .worktreeinclude |

Monorepos can reduce checkout size with sparsePaths and symlinkDirectories; see [Large codebases](https://docs.passion8.cc/en/docs/claude-code/large-codebases). Desktop parallel sessions can create worktrees automatically; this guide focuses on CLI.

## Start a worktree session

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

| Item | Default |
| --- | --- |
| Directory | .claude/worktrees/<name>/ under repository root |
| Branch | worktree-<name> |

Start another isolated task:

```bash
claude --worktree bugfix-123
```

Or generate a name:

```bash
claude --worktree
```

You can also ask Claude to work in a worktree. EnterWorktree creates and enters it; switching to another managed worktree leaves the original on disk.




Before first interactive worktree use, run Claude in the repository and accept workspace trust. Otherwise the command asks you to trust it first. Noninteractive print-mode worktrees skip that interactive trust check.




Ignore generated directories:

```gitignore
.claude/worktrees/
```

## Base branch

By default, new worktrees start from origin/HEAD, falling back to local HEAD if no remote is available or fetch fails.

To include the current branch's unpushed commits:

```json title=".claude/settings.json"
{
  "worktree": {
    "baseRef": "head"
  }
}
```

| Value | Meaning |
| --- | --- |
| fresh | Prefer origin/HEAD; default |
| head | Current local HEAD |

For a GitHub PR, use a #number or full PR URL:

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

Claude fetches pull/<number>/head from origin and creates .claude/worktrees/pr-<number>.

## Copy local configuration

A new checkout does not automatically include untracked .env files or local secrets. A root .worktreeinclude uses gitignore-style patterns to copy selected ignored files:

```text title=".worktreeinclude"
.env
.env.local
config/secrets.json
```

| Boundary | Detail |
| --- | --- |
| Ignored files only | Tracked files are not copied through this mechanism |
| Multiple entry points | CLI, subagent worktrees, Desktop parallel sessions |
| Custom WorktreeCreate | Must implement copying yourself |




Never commit real keys. Prefer user settings or shell variables for Passion8 credentials; copy project env files only when the task needs them.




## Subagent isolation

```markdown title=".claude/agents/fixer.md"
---
name: fixer
description: Fix an independent issue in an isolated worktree.
tools: Read, Grep, Glob, Edit, Bash
isolation: worktree
---

Keep the change focused. Report changed files and validation results when finished.
```

You can request worktrees for agents directly. Their base strategy is the same: remote default unless baseRef is head. Unchanged temporary worktrees are removed; changed ones retain information for review.

## Cleanup

| State on exit | Behavior |
| --- | --- |
| No changes, untracked files, or new commits | Remove workspace/branch; named sessions may prompt to keep |
| Any changes or new commits | Ask to keep or delete; deletion discards them |
| Print mode | No automatic exit cleanup; remove manually |

Periodic cleanup of subagent/background worktrees requires:

- Older than cleanupPeriodDays.
- No uncommitted changes.
- No untracked files.
- No unpushed commits.

Explicit --worktree workspaces are not removed by that background sweep. Active agent worktrees are locked against concurrent cleanup and unlocked after completion.

## Manual management

For explicit location/branch control:

```bash
git worktree add ../project-feature-a -b feature-a
```

```bash
git worktree add ../project-bugfix bugfix-123
```

Start Claude inside it:

```bash
cd ../project-feature-a
claude
```

| Command | Purpose |
| --- | --- |
| git worktree list | List workspaces |
| git worktree remove ../project-feature-a | Remove a clean workspace |
| git worktree remove --force ../project-feature-a | Discard a workspace containing uncommitted changes |

Each directory needs the project's applicable dependencies, virtual environments, generated files, and initialization steps.

## Other version-control systems

For SVN, Perforce, Mercurial, or custom isolation, implement WorktreeCreate/WorktreeRemove hooks:

```json title=".claude/settings.json"
{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}
```

The hook reads the requested name from stdin, creates a directory, and prints its path. It replaces Git creation and must handle local configuration copying itself.

## Common mistakes

| Mistake | Result | Correction |
| --- | --- | --- |
| Expect env files automatically | Missing local configuration | User settings, shell env, or worktreeinclude |
| Expect local unpushed commits under fresh mode | Starts from remote base | Use baseRef head |
| Commit .claude/worktrees | Unwanted nested checkouts | Add ignore entry |
| Expect print-mode cleanup | Workspace remains | Remove manually |
| Agents edit one checkout | Conflicts and stale context | Isolate writers |

## Official references

- [Worktrees](https://code.claude.com/en/docs/en/worktrees.md)
- [Subagents](https://code.claude.com/en/docs/en/sub-agents.md)
- [Settings](https://code.claude.com/en/docs/en/settings.md)
- [Hooks](https://code.claude.com/en/docs/en/hooks.md)
- [Git worktree](https://git-scm.com/en/docs/git-worktree)