Help us improve
Share bugs, ideas, or general feedback.
From agentops
Isolates parallel Claude Code workers in separate git worktrees to prevent file collisions during concurrent edits.
npx claudepluginhub boshu2/agentops --plugin agentopsHow this skill is triggered — by the user, by Claude, or both
Slash command
/agentops:cc-worktree-isolationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Make parallel agent writes safe. Each concurrent worker gets its own git worktree (its own working directory + branch), so two subagents editing the repo at the same time can never step on each other's uncommitted files. This is the Claude-native first move; manual `git worktree` is the fallback for non-Claude runtimes.
Creates, lists, and cleans up Git worktrees for parallel Claude Code sessions on separate branches, enabling conflict-free multi-feature development.
Sets up Git worktrees for running multiple parallel Claude sessions on the same repo without conflicts. Use for review, refactor, test, and docs workflows with isolated directories.
Creates and manages git worktrees for parallel coding sessions while waiting on tests, builds, CI, or during code review and exploration.
Share bugs, ideas, or general feedback.
Make parallel agent writes safe. Each concurrent worker gets its own git worktree (its own working directory + branch), so two subagents editing the repo at the same time can never step on each other's uncommitted files. This is the Claude-native first move; manual git worktree is the fallback for non-Claude runtimes.
When you fan out work across parallel subagents or an NTM swarm in a single repo, the failure mode is collision: worker A writes foo.ts, worker B writes foo.ts, and one set of edits is silently lost or merges into garbage. Worktree isolation removes the shared mutable surface — every writer operates in a physically separate checkout.
Three Claude-native levers (verified against Claude Code 2.1.x):
claude --worktree (-w) starts the whole session in a fresh isolated worktree.isolation: worktree in a .claude/agents/*.md frontmatter — each spawn of that teammate gets its own worktree automatically.EnterWorktree / ExitWorktree tools create/leave a worktree mid-session (created under .claude/worktrees/).Plus two tuning knobs: the worktree.sparsePaths setting (limit the checkout to relevant subtrees in big monorepos) and WorktreeCreate / WorktreeRemove hooks (VCS-agnostic isolation + audit/cleanup).
foo.ts, you still get a merge conflict, just later and harder. Assign file ownership upfront (the workspace rule: if two tasks touch the same file, combine into one worker)..claude/worktrees/.EnterWorktree with name while already in a worktree session; switching into an existing worktree via path is allowed. Why: nested fresh worktrees produce ambiguous cleanup and base-ref confusion.worktree.baseRef governs where new worktrees branch from: fresh (default) = origin/<default-branch>; head = current local HEAD. Why: fresh workers won't see your uncommitted local changes — set head if they must.ExitWorktree action: remove REFUSES if there are uncommitted files or unmerged commits unless discard_changes: true. Why: this is the guard against deleting real work — confirm with the operator before forcing it.claude -p for workers. This is operator/flywheel infrastructure. Why: claude -p bills the API per token, not the Max subscription — banned for Claude workers. Use NTM panes or spawned subagents.Pick the isolation lever by how workers are spawned:
| Spawn shape | Lever |
|---|---|
Custom teammates via .claude/agents/*.md | isolation: worktree in frontmatter (declarative — preferred) |
| A whole side session | claude --worktree / -w |
| Mid-session, one-off isolated branch | EnterWorktree tool |
| NTM swarm panes / non-Claude runtime | WorktreeCreate hook or manual git worktree add |
Confirm file-ownership boundaries are non-overlapping before any spawn (see Constraints).
Checkpoint: Every planned writer has a disjoint file set AND a chosen isolation lever. If two writers share a file, stop and merge them into one worker.
Declarative agent (preferred):
# .claude/agents/implementer.md
---
description: Implements one bead end to end
model: claude-opus-4-8
isolation: worktree
background: true
---
Sparse checkout for large monorepos (.claude/settings.json):
{ "worktree": { "baseRef": "fresh", "sparsePaths": ["packages/api", "packages/shared"] } }
Audit/cleanup hooks (.claude/settings.json) — WorktreeCreate / WorktreeRemove also provide VCS-agnostic isolation outside git:
{ "hooks": {
"WorktreeCreate": [{ "hooks": [{ "type": "command", "command": "echo \"$(date -u) created $CLAUDE_WORKTREE_PATH\" >> .claude/worktree-audit.log" }] }],
"WorktreeRemove": [{ "hooks": [{ "type": "command", "command": "echo \"$(date -u) removed $CLAUDE_WORKTREE_PATH\" >> .claude/worktree-audit.log" }] }]
} }
Checkpoint: claude agents lists the isolated teammate; settings parse without error. Sparse paths cover every file each worker needs.
Spawn workers. For mid-session isolation, EnterWorktree { name: "bead-ag-123" } creates .claude/worktrees/bead-ag-123 on a new branch and switches CWD into it. Layer agent-mail file reservations on top when swarm members might still converge on a shared path — worktrees stop the filesystem clobber, agent-mail prevents two workers choosing the same file.
Checkpoint: Each worker reports its worktree path/branch. No two report the same branch.
ExitWorktree { action: "remove" } per worker (or keep to preserve). If it refuses, inspect the listed changes, then re-invoke with discard_changes: true only after operator confirmation. Manual fallback: git worktree remove <path> && git branch -d <branch>.Checkpoint: git worktree list shows only the canonical tree; git branch has no orphaned worker branches; audit log matches.
Format: repo state + a short merge/cleanup report (markdown to stdout or the session log).
Filename: optional audit trail at .claude/worktree-audit.log (created/removed events); no other file is mandated.
Structure: the report names each worker's worktree path + branch, the merge order applied, conflicts resolved, and the final git worktree list / git branch state proving zero orphans.
isolation: worktree preferred over shell choreography).worktree.baseRef was chosen deliberately (fresh vs head), not defaulted blindly.EnterWorktree create-nesting; existing-worktree entry used path.git worktree list + git branch show no orphans; no work silently discarded.claude -p used for any worker.Fan-out across three beads: define three implementer teammates with isolation: worktree, assign each a disjoint package, spawn, merge in bead-dependency order, remove worktrees.
Monorepo subtree work: set worktree.sparsePaths: ["services/billing"] so each worker checks out only billing — faster, and structurally impossible to touch unrelated code.
Mid-session hotfix isolation: operator says "do this in a worktree" → EnterWorktree { name: "hotfix-payments" } → fix → commit → ExitWorktree { action: "remove" }.
| Problem | Cause | Solution |
|---|---|---|
EnterWorktree rejected | Already in a worktree session (with name) | Use path to switch into an existing worktree, or ExitWorktree first |
| Worker can't see local changes | worktree.baseRef: fresh branches from origin | Set baseRef: head, or push changes first |
ExitWorktree remove refuses | Uncommitted/unmerged work present | Inspect listed changes; commit/merge, or confirm then discard_changes: true |
| Merge conflicts despite isolation | Two workers edited the same file | Phase-1 ownership failure — combine those tasks next time |
path entry rejected | Path not in git worktree list for this repo | Only registered worktrees of the current repo are enterable |
| Isolation ignored in non-Claude runtime | Tool unavailable | Fall back to WorktreeCreate hook or manual git worktree add |
../shared/references/claude-code-latest-features.md) — §2 Agent Definitions, §3 Worktree Isolation, §4 Hooks (the authoritative feature set; re-verify against the upstream changelog before relying on a flag).cc-hooks skill — authoring WorktreeCreate / WorktreeRemove and other governance hooks.agent-mail skill — file reservations that complement worktrees for swarm coordination.ntm / vibing-with-ntm skills — spawning the parallel workers that consume this isolation.https://code.claude.com/docs/en/sub-agents, https://code.claude.com/docs/en/cli-reference.