worktree-manager（工作树管理器）

<quick_start> Create a single worktree with agent:

/worktree create feature/auth

Claude will:

1. Allocate ports (8100-8101)
2. Create worktree at ~/tmp/worktrees/[project]/feature-auth
3. Install dependencies
4. Create WORKTREE_TASK.md for the agent
5. Launch terminal with Claude Opus 4.6 agent </quick_start>

Native --worktree Flag (Claude Code v2.1.49+)

Claude Code now has built-in worktree support:

# Named worktree
claude --worktree feature-auth   # or: claude -w feature-auth

# Auto-generated name
claude -w

What It Does

• Creates worktree at <repo>/.claude/worktrees/<name>/
• Branch: worktree-<name> (auto-created from default remote branch)
• On exit: auto-cleanup if no changes; prompts to keep/remove if changes exist

Tip: Add .claude/worktrees/ to .gitignore

When to Use Native vs This Skill

WorktreeCreate / WorktreeRemove Hooks

New hook events for VCS-agnostic worktree lifecycle. These replace the default git worktree behavior when configured:

{
  "hooks": {
    "WorktreeCreate": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'INPUT=$(cat); NAME=$(echo \"$INPUT\" | jq -r .name); mkdir -p /tmp/worktrees/$NAME && echo $NAME'"
      }]
    }],
    "WorktreeRemove": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'INPUT=$(cat); PATH=$(echo \"$INPUT\" | jq -r .path); rm -rf $PATH'"
      }]
    }]
  }
}

When to use hooks vs native: Use hooks when working with non-git VCS systems or when you need custom isolation logic (e.g., Docker containers, remote dev servers). For standard git repos, the native claude -w flag or this skill's workflow is preferred.

Note: These hooks do NOT support matchers. They fire once per worktree lifecycle event. The hook receives {name, path} via stdin JSON.

<success_criteria> A worktree setup is successful when:

• Worktree created at ~/tmp/worktrees/[project]/[branch-slug]
• Ports allocated and registered globally
• Dependencies installed
• Agent launched in terminal (Ghostty/iTerm2/tmux)
• Entry added to ~/.claude/worktree-registry.json </success_criteria>

<current_state> Git repository:!git status --short --branch 2>/dev/null

Existing worktrees:!git worktree list 2>/dev/null

Worktree registry:!cat ~/.claude/worktree-registry.json 2>/dev/null | jq -r '.worktrees[] | "\(.project)/\(.branch) → \(.status)"' | head -10

Available ports:!cat ~/.claude/worktree-registry.json 2>/dev/null | jq '.portPool.allocated | length' || echo "0" allocated </current_state>

<activation_triggers>

When This Skill Activates

Trigger phrases:

• "spin up worktrees for X, Y, Z"
• "create 3 worktrees for features A, B, C"
• "new worktree for feature/auth"
• "what's the status of my worktrees?"
• "show all worktrees" / "show worktrees for this project"
• "clean up merged worktrees"
• "launch agent in worktree X"

Invocation

Command syntax:

• /worktree create feature/auth - Single worktree
• /worktree create feat1 feat2 feat3 - Multiple worktrees
• /worktree status - Check all worktrees
• /worktree status --project myapp - Filter by project
• /worktree cleanup feature/auth - Remove worktree
• /worktree launch feature/auth - Launch agent in worktree

</activation_triggers>

<file_locations>

Key Files

</file_locations>

<core_concepts>

Core Concepts

Centralized Worktree Storage

All worktrees live in ~/tmp/worktrees/<project-name>/<branch-slug>/

~/tmp/worktrees/
├── obsidian-ai-agent/
│   ├── feature-auth/           # branch: feature/auth
│   ├── feature-payments/       # branch: feature/payments
│   └── fix-login-bug/          # branch: fix/login-bug
└── another-project/
    └── feature-dark-mode/

Branch Slug Convention

Branch names are slugified for filesystem safety:

• feature/auth → feature-auth
• fix/login-bug → fix-login-bug

Slugify manually: echo "feature/auth" | tr '/' '-'

Port Allocation

• Global pool: 8100-8199 (100 ports total)
• Per worktree: 2 ports allocated (for API + frontend patterns)
• Globally unique: Ports tracked to avoid conflicts across projects

See: reference/port-allocation.md for detailed operations.

Required Defaults

CRITICAL: These settings MUST be used when launching agents:

Launch command pattern:

# Recommended: agent inherits .claude/ config (CLAUDE.md, hooks, permissions)
claude --model opus --dangerously-skip-permissions

# Or with explicit permission allowlist (safer, from .claude/settings.json):
claude --model opus --allowedTools "Bash(npm test),Bash(npm run build),Edit,Write,Read,Glob,Grep"

Subagent Worktree Isolation

Subagents can be configured to run in isolated worktrees:

# In subagent frontmatter:
---
name: my-subagent
isolation: worktree
---

The subagent runs in a temporary worktree. On completion:

• If no changes: auto-cleanup
• If changes exist: changes preserved for review

</core_concepts>

Skill Config

Location: ~/.claude/skills/worktree-manager/config.json

{
  "terminal": "ghostty",
  "terminalPreference": "auto",
  "enableNumberedTabs": true,
  "shell": "zsh",
  "defaultModel": "opus",
  "claudeCommand": "claude --model opus --dangerously-skip-permissions",
  "portPool": { "start": 8100, "end": 8199 },
  "portsPerWorktree": 2,
  "worktreeBase": "~/tmp/worktrees",
  "defaultCopyDirs": [".claude"],
  "envFilePriority": [".env.local", ".env", ".env.example"],
  "autoCleanupOnMerge": true
}

.claude/ Directory Propagation

When creating worktrees, the entire .claude/ directory is copied so agents inherit project-level config:

.claude/
├── CLAUDE.md              # Project instructions (auto-loaded by Claude Code)
├── settings.json          # Hooks and permissions
│   ├── hooks.PostToolUse  # Auto-format on Write|Edit (e.g., "bun run format || true")
│   └── permissions.allow  # Whitelisted bash commands for agents
├── agents/                # Custom subagent definitions
│   ├── build-validator.md # Validates builds pass
│   ├── code-architect.md  # Plans implementation
│   ├── code-simplifier.md # Refactors for clarity
│   └── verify-app.md      # End-to-end verification
└── PROJECT_CONTEXT.md     # Session continuity (project-context-skill)

Why this matters:

• CLAUDE.md: Agent reads project conventions, dev commands, tech stack
• Hooks: Auto-formatting runs after every Write/Edit, keeping code consistent across agents
• Permissions: Agents can run pre-approved commands without prompting (e.g., npm test, bun run build)
• Custom agents: Agents can dispatch subagents (e.g., verify-app.md for end-to-end checks)

Hook example (settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "bun run format || true" }]
      }
    ]
  }
}

Workflows

Create Multiple Worktrees

User says: "Spin up 3 worktrees for feature/auth, feature/payments, and fix/login-bug"

You do (can parallelize with subagents):

For EACH branch (can run in parallel):

1. SETUP
   PROJECT=$(basename $(git remote get-url origin 2>/dev/null | sed 's/\.git$//') || basename $(pwd))
   REPO_ROOT=$(git rev-parse --show-toplevel)
   BRANCH_SLUG=$(echo "feature/auth" | tr '/' '-')
   WORKTREE_PATH=~/tmp/worktrees/$PROJECT/$BRANCH_SLUG

2. ALLOCATE PORTS
   Find 2 unused ports from 8100-8199, add to registry

3. CREATE WORKTREE
   mkdir -p ~/tmp/worktrees/$PROJECT
   git worktree add $WORKTREE_PATH -b $BRANCH

4. COPY PROJECT CONFIG (.claude/ directory)
   cp -r .claude $WORKTREE_PATH/ 2>/dev/null || true
   Copy .env.local or .env as appropriate

5. CREATE WORKTREE_TASK.md
   Create detailed task file for agent

6. INSTALL DEPENDENCIES
   Detect package manager, run install command

7. VALIDATE (optional)
   Start server, health check, stop

8. REGISTER IN GLOBAL REGISTRY
   Update ~/.claude/worktree-registry.json with entry

9. LAUNCH AGENT
   ghostty -e "cd $WORKTREE_PATH && claude --model opus --dangerously-skip-permissions"

AFTER ALL COMPLETE:
- Report summary table to user

Check Status

With script:

~/.claude/skills/worktree-manager/scripts/status.sh
~/.claude/skills/worktree-manager/scripts/status.sh --project my-project

Manual:

cat ~/.claude/worktree-registry.json | jq -r '.worktrees[] | "\(.project)\t\(.branch)\t\(.ports | join(","))\t\(.status)"'

Cleanup Worktree

See: reference/cleanup-operations.md for full cleanup procedure.

Quick cleanup:

~/.claude/skills/worktree-manager/scripts/cleanup.sh <project> <branch> --delete-branch

Reference Files

For detailed operations, see:

<safety_guidelines>

Safety Guidelines

1. Before cleanup, check PR status:

- PR merged → safe to clean everything - PR open → warn user, confirm before proceeding - No PR → warn about unsubmitted work

1. Before deleting branches, confirm if:

- PR not merged - No PR exists - Worktree has uncommitted changes

1. Port conflicts: If port in use by non-worktree process, pick different port
2. Environment files: Never commit .env or .env.local to git

</safety_guidelines>

<example_session>

Example Session

User: "Spin up 2 worktrees for feature/dark-mode and fix/login-bug"

You:

1. Detect project: obsidian-ai-agent (from git remote)
2. Detect package manager: uv (found uv.lock)
3. Allocate 4 ports: 8100 8101 8102 8103
4. Create worktrees: git worktree add ~/tmp/worktrees/obsidian-ai-agent/feature-dark-mode -b feature/dark-mode git worktree add ~/tmp/worktrees/obsidian-ai-agent/fix-login-bug -b fix/login-bug
5. Copy.claude/ and.env to each
6. Install deps: (cd <path> && uv sync)
7. Register both in ~/.claude/worktree-registry.json
8. Launch agents: ghostty -e "cd ~/tmp/worktrees/.../feature-dark-mode && claude --model opus --dangerously-skip-permissions"
9. Report: Created 2 worktrees with agents: | Branch | Ports | Path | Task | |--------|-------|------|------| | feature/dark-mode | 8100, 8101 | ~/tmp/worktrees/.../feature-dark-mode | Implement dark mode | | fix/login-bug | 8102, 8103 | ~/tmp/worktrees/.../fix-login-bug | Fix login redirect | Both agents running in Ghostty windows.

</example_session>

Boris Cherny Workflow Integration

iTerm2 notifications, web session handoff (/teleport), ralph-loop for autonomous sessions, and daily workflow protocols.

See reference/advanced-workflows.md for iTerm2 setup, teleport handoff, ralph-loop patterns, terminal strategy, and daily workflow protocol.

Emit Outcome Sidecar

As the final step, write to ~/.claude/skill-analytics/last-outcome-worktree-manager.json:

{"ts":"[UTC ISO8601]","skill":"worktree-manager","version":"1.2.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"worktrees_created":[n],"agents_launched":[n],"worktrees_cleaned":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

Use status "partial" if some stages failed but results were produced. Use "error" only if no output was generated.