Worktree Isolation

What You’ll Learn

Git worktrees let parallel Claude Code sessions edit separate checkouts and branches without touching one another’s files. Claude Code now exposes this isolation directly through CLI flags, in-session tools, and subagent configuration.

This session covers the supported lifecycle: create, initialize, work, resume, integrate, and clean up.

What a Worktree Isolates

A Git worktree is another working directory with its own checked-out files and branch. It shares the repository’s history and remotes with the main checkout.

repository
├── main checkout                 branch: main
└── .claude/worktrees/feature-auth
                                  branch: worktree-feature-auth

The isolation boundary is the filesystem checkout. It does not isolate external services, credentials, ports, databases, package caches, or every Git operation. Coordinate those resources separately.

Worktrees also do not coordinate agents. Use subagents or Agent Teams for delegation and communication; use worktrees to prevent file edits from colliding.

Start an Isolated Session

Pass a name to --worktree or -w:

claude --worktree feature-auth
# equivalent
claude -w feature-auth

By default Claude Code creates .claude/worktrees/feature-auth/ and a branch named worktree-feature-auth. Use a different name in another terminal for another isolated session. Add the generated directory to your ignore rules:

.claude/worktrees/

You can also ask Claude to “work in a worktree” during an existing session. Claude Code enters one through its supported worktree tools; you do not need to reproduce that transition with a custom event stream.

Initialize the Fresh Checkout

A worktree contains tracked files, not all local machine state. Install dependencies there and recreate any required local configuration.

For gitignored files that every Claude-created worktree needs, add a .worktreeinclude file at the repository root using .gitignore syntax:

.env.local
config/dev-secrets.json

Only matching files that are already gitignored are copied. Treat this as convenience, not a secrets policy: keep sensitive files minimal and review who can read the worktree.

Isolate a Custom Subagent

Ask Claude to use worktrees for agents, or make isolation part of a custom subagent definition:

---
name: refactorer
description: Applies mechanical refactors across independent files
isolation: worktree
---

Apply the requested refactor, run the affected tests, and report the commit.

Claude Code creates a temporary worktree for that subagent. A clean temporary worktree can be removed automatically; one containing changes remains until it can be cleaned without losing work.

Cleanup Is a State Decision

When an interactive worktree session exits, Claude Code checks for changed or untracked files and new commits.

State	Interactive behavior
Clean, unnamed worktree	Worktree and branch are removed automatically
Clean, named worktree	Claude Code asks whether to keep it
Contains work	Claude Code asks whether to keep or remove it
Non-interactive -p run	No exit prompt and no automatic cleanup

Removing a worktree that contains work deletes its directory and branch, including that work. Read the prompt and verify the target before accepting removal.

For non-interactive runs or manual management, use Git’s public commands:

git worktree list
git worktree remove .claude/worktrees/feature-auth
git worktree prune

Do not add --force unless you have deliberately decided to discard uncommitted or untracked work.

Resume and Integrate

Resuming a session that was inside a worktree returns it to that worktree when the directory still exists. A fork with --fork-session starts from the directory where you launch Claude and leaves the original worktree unchanged.

Before integration:

1. run the affected tests inside the worktree;
2. inspect git status and git diff;
3. commit the bounded change;
4. merge, cherry-pick, or open a PR using your normal Git workflow;
5. remove the worktree only after the work is safely integrated or intentionally discarded.

What Not to Assume

• Worktrees are separate checkouts; the public contract does not guarantee a particular file-copy implementation.
• A clean filesystem does not prove external side effects are isolated.
• Auto-cleanup rules differ between interactive sessions, subagents, and -p runs.
• Undocumented directory internals are not a stable orchestration API.

Official Sources

• Run parallel sessions with worktrees
• Claude Code CLI reference

Next Session

Next, use the Agent SDK’s public API to build a programmable agent without depending on Claude Code internals.