Worktree Isolation

Design, audit, and operate Claude Code worktree isolation for parallel sessions, subagents, and custom worktree hooks. Prefer this skill when the request involves claude --worktree, claude -w, .claude/worktrees/<name>, .worktreeinclude, EnterWorktree, WorktreeCreate, WorktreeRemove, or subagent frontmatter with isolation: worktree. [DOC]

Use official Claude Code documentation as the active source of truth. If the local Claude Code version, trust state, settings files, or remote default branch cannot be verified, state coverage_gap rather than guessing. [DOC][INFERENCIA]

Supporting files:

• references/claude-code-worktree-behavior.md - CLI, EnterWorktree, base branch, .worktreeinclude, subagent, and cleanup behavior. [DOC]
• references/hooks-and-custom-vcs.md - WorktreeCreate and WorktreeRemove hook boundaries, custom VCS behavior, and .worktreeinclude caveats. [DOC]
• references/coordination-boundaries.md - When worktrees solve file isolation and when explicit coordination is still required. [INFERENCIA]
• assets/worktree-readiness-checklist.md - Preflight checklist before starting or recommending worktree sessions. [CONFIG]
• assets/worktree-cleanup-checklist.md - Cleanup checklist for finished, kept, stale, and subagent worktrees. [CONFIG]
• scripts/check.sh - Deterministic package check for eval, asset, fixture, and required-term coverage. [CONFIG]

Inputs Expected

• Repository path and current task intent.
• Desired isolation surface: manual Claude session, parallel terminal, subagent, background session, custom VCS, or hook-managed worktree.
• Branching intent: remote-clean default branch, current local HEAD, existing branch, or specific pull request.
• Local state that must be available in the worktree: env files, secrets config, ignored caches, dependency directories, or sparse checkout needs.
• Coordination context: owners, branch names, shared files, merge order, validation gates, and conflict boundaries.

Outputs Expected

• A worktree recommendation or implementation plan with commands, settings, hook snippets, and cleanup steps.
• Explicit branch/baseRef decision: default fresh, configured head, manual Git worktree, or PR worktree.
• Explicit local-file policy for .worktreeinclude, hook-side copying, or directory-sharing/sparse-slice settings where confirmed available.
• Conflict-avoidance and coordination notes, including cases where worktrees isolate files but do not coordinate agents.
• Validation packet with evidence tags and any coverage_gap.

Core Rules

Use claude --worktree <name> or claude -w <name> to start Claude in an isolated git worktree. Default placement is .claude/worktrees/<name>/, with a branch named worktree-<name>. If no name is provided, Claude generates one. Add .claude/worktrees/ to .gitignore so worktree contents do not appear as untracked files in the main checkout. [DOC]

Confirm workspace trust before recommending an interactive --worktree run in a directory. Run claude once in the directory to accept the trust dialog. Interactive --worktree exits with an error if trust has not been accepted. Non-interactive claude -p --worktree skips the trust check. [DOC]

Select the base deliberately. The default worktree.baseRef behavior is fresh, which branches from origin/<default-branch> for a clean remote-aligned tree and falls back to local HEAD only if no remote is configured or fetch fails. Set "worktree": {"baseRef": "head"} only when new worktrees must inherit current local commits and branch state. The setting accepts only "fresh" or "head". [DOC]

Use .worktreeinclude for gitignored files that must be copied into new Claude-created worktrees. The file uses .gitignore syntax, and only files that both match a pattern and are gitignored are copied. Tracked files are not duplicated. Treat copied secrets as sensitive local state and avoid committing the include file if it reveals private paths. [DOC][INFERENCIA]

Use subagent isolation: worktree when a delegated agent may edit files in parallel with the parent or other agents. Each isolated subagent receives a temporary worktree using the same baseRef behavior as --worktree. A no-change subagent worktree is removed automatically; changed worktrees require merge, cleanup, or explicit preservation. [DOC]

Use EnterWorktree for in-session switching or creation. Passing a path switches into an existing worktree of the current repository. From inside a worktree session, or from a subagent pinned with isolation: worktree, only the path form is available and the target must be under .claude/worktrees/. [DOC]

Use WorktreeCreate hooks only when default git worktree creation is insufficient, such as custom locations, non-git VCS, or repository-specific setup. A WorktreeCreate hook replaces default git behavior entirely; .worktreeinclude is not processed in that mode, so copy needed local files inside the hook. Use WorktreeRemove for cleanup and archiving; it cannot block removal. [DOC]

Treat cleanup as part of the plan. On exit, unchanged unnamed worktrees can be removed automatically, named sessions prompt, changed sessions prompt, and non-interactive -p --worktree worktrees are not auto-cleaned. Use git worktree list, git status, git log @{u}..HEAD, and git worktree remove only after confirming whether changes, untracked files, or unpushed commits must be preserved. [DOC][INFERENCIA]

Procedure

1. Locate State

Read the current repository path, git root, branch, remotes, .gitignore, .claude/settings.json, .claude/settings.local.json, and existing .claude/worktrees/ entries when available. Avoid mutating anything during discovery. [CÓDIGO][CONFIG]

2. Choose Isolation Mode

Choose one path:

• --worktree or -w for a named interactive parallel Claude session.
• EnterWorktree for switching or creating a worktree inside an active session.
• Subagent isolation: worktree for parallel delegated edits.
• Manual git worktree add for existing branches, custom branch names, or locations outside .claude/worktrees/.
• WorktreeCreate and WorktreeRemove hooks for custom VCS or fully controlled creation/removal.

3. Set Branch And Local Files

State the selected baseRef and reason. Add .worktreeinclude only for ignored files required by the session. Use worktree.symlinkDirectories for large directories that should be shared instead of copied, and worktree.sparsePaths for large monorepos where each worktree needs only a slice of the repository. [DOC]

4. Define Coordination

Assign branch names, file ownership, dependency order, and merge order before parallel work begins. Worktrees prevent simultaneous edits from touching the same working directory; they do not decide which changes win, synchronize requirements, or merge branches safely. [INFERENCIA]

5. Validate And Close

Apply assets/worktree-readiness-checklist.md before starting work and assets/worktree-cleanup-checklist.md before removal. Run the smallest repository validation needed for each worktree before merge. Report commands run, results, preserved worktrees, removed worktrees, and residual coverage_gap.

Quality Criteria

• The output names the isolation mode and why it fits the task.
• The output states baseRef behavior, including whether remote-clean fresh or local head is required.
• The output handles trust dialog requirements before interactive --worktree.
• The output includes .gitignore and .worktreeinclude guidance when Claude-created worktrees are used.
• The output distinguishes gitignored-file copying from tracked-file checkout.
• The output covers WorktreeCreate and WorktreeRemove hook effects when hooks are proposed.
• The output covers subagent isolation: worktree cleanup and baseRef behavior when subagents are involved.
• The output explains cleanup conditions and avoids deleting changed worktrees without explicit confirmation.
• The output states what coordination remains outside worktree isolation.

Usage

• /worktree-isolation
• run Claude Code in a worktree for this feature
• set up isolation: worktree for this subagent
• audit our .worktreeinclude and WorktreeCreate hook
• clean up stale .claude/worktrees safely

Contract

• Aceptación: worktree temporal por rama paralela; se limpia si no hubo cambios. [EXPLICIT]
• Límites: aísla el checkout; no resuelve conflictos de merge. [EXPLICIT]
• Casos borde: costo de setup ~200-500ms + disco por agente — usar solo si hay escrituras paralelas reales. [EXPLICIT]
• Supuestos: EnterWorktree/ExitWorktree + Agent isolation:"worktree" [CÓDIGO]. [SUPUESTO]
• Trade-off: aislamiento fuerte a cambio de overhead — no usar para tareas read-only. [EXPLICIT]

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): references/ guías de profundidad (cargar UNA por etapa) · knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output · scripts/ automatización local · assets/ recursos estáticos.