Using Worktrees For Parallel Claude Code Sessions

TL;DR

Git worktrees give each Claude Code session its own checkout so parallel agents do not stomp the same files. Create one worktree per task, launch Claude Code inside each path, use EnterWorktree or background isolation defaults, and prune .claude/worktrees/ when jobs complete.

Prerequisites & Requirements

• {"task": "Worktree policy", "description": "Team agrees when worktrees are required versus branch switching"}
• {"task": "Disk budget", "description": "Developers have space for multiple linked checkouts"}
• {"task": "Isolation settings reviewed", "description": "worktree.bgIsolation defaults are documented"}
• {"task": "Cleanup owner", "description": "Someone prunes stale worktrees weekly"}
• {"task": "Sandbox retest", "description": "Autonomous agents were validated inside worktrees if used"}

Core Concepts Explained

Worktrees isolate working directories

Official worktree docs describe linked checkouts that share git history but keep working files separate—ideal for parallel Claude Code sessions on different tasks.

EnterWorktree moves agents into isolation

Background and subagent flows can call EnterWorktree so edits land in an isolated checkout instead of the shared working tree.

Background isolation can be relaxed deliberately

Release notes document worktree.bgIsolation: "none" for cases where background sessions must edit the primary checkout—treat that as a conscious exception.

Cleanup prevents disk drift

Background retention sweeps and manual pruning of .claude/worktrees/ keep orphan checkouts from accumulating after parallel runs.

Step-by-Step Implementation Guide

1. Pick tasks that truly need parallelism. Use worktrees when two agents must edit different branches simultaneously.

2. Create linked checkouts. Add a worktree per branch with clear directory names tied to ticket IDs.

3. Launch Claude Code per worktree. Open CLI or Desktop sessions from each checkout path—not from the repo root alone.

4. Enable isolation defaults. Keep background isolation on unless policy documents an approved worktree.bgIsolation: "none" exception.

5. Use EnterWorktree in workflows. For background agents and subagents, confirm isolation before approving write tools.

6. Retest sandbox rules. Validate autonomous bash policies inside worktrees when sandbox write allowlists differ from the main checkout.

7. Prune on completion. Remove finished worktrees and clean .claude/worktrees/ during daily or weekly hygiene.

Parallel Session Checklist

• {"task": "One worktree per task", "description": "No two active agents share one checkout unintentionally"}
• {"task": "Branch ownership clear", "description": "Each worktree maps to one merge owner"}
• {"task": "Isolation verified", "description": "EnterWorktree or bgIsolation policy matches the task risk"}
• {"task": "Sandbox validated", "description": "Autonomous tools were tested in the linked checkout if used"}
• {"task": "Cleanup scheduled", "description": "Stale worktrees are removed after jobs finish"}

Troubleshooting

Agent edited files in the wrong checkout

Confirm session cwd and re-dispatch from the intended worktree path.

Orphan directories under .claude/worktrees/

Prune after background jobs finish; release notes cover retention sweeps tied to background session lifecycle.

Sandbox writes fail only in worktrees

Review sandbox write allowlists and symlinked settings paths documented in release notes for worktree-specific fixes.

Shared checkout races despite worktrees

Check for sessions still running in the primary tree or bgIsolation set to none.

Source Verification Notes

Verified against official Claude Code documentation on 2026-06-15:

• code.claude.com/docs/en/worktrees documents Claude Code worktree workflows including parallel session patterns and EnterWorktree behavior.
• Public CHANGELOG.md entries describe worktree isolation guards for background subagents, .claude/worktrees/ cleanup, worktree.bgIsolation: "none", and sandbox write allowlist fixes for linked checkouts.

Duplicate Check

Checked content/guides and open pull requests for Claude Code worktrees, parallel sessions, and EnterWorktree workflows. Sandbox and dynamic workflow guides mention worktrees tangentially. This guide is the dedicated parallel-session worktree workflow.

References

• Worktrees docs - https://code.claude.com/docs/en/worktrees
• Agent view guide - agent-view-for-managing-multiple-claude-code-sessions
• Desktop parallel sessions - claude-code-desktop-parallel-sessions-workflow