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.5 agent </quick_start>

<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"

</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

2. Before deleting branches, confirm if:

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

3. Port conflicts: If port in use by non-worktree process, pick different port

4. 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

Based on Boris Cherny’s (Claude Code creator) 13-step autonomous workflow.

iTerm2 Notifications Setup

Enable system notifications when Claude needs input (Boris runs 5 numbered tabs):

Step 1: iTerm2 Preferences

1. iTerm2 → Preferences → Profiles → Terminal
2. Enable “Notification when idle”
3. Set “After 30 seconds of silence, send notification”

Step 2: Shell Integration (Optional)

# Add to ~/.zshrc for manual attention requests
it2attention() { printf "\e]1337;RequestAttention=fireworks\a"; }

Step 3: Tab Numbering The launch-agent.sh script automatically numbers iTerm2 tabs as [1] project - branch, [2] project - branch, etc. when using --terminal iterm2.

Web Session Handoff (Teleport)

Hand off local session to claude.ai/code for longer tasks or mobile monitoring:

# In terminal Claude session, run:
/teleport

# Or use ampersand for background handoff:
claude & teleport

Workflow:

1. Start work in terminal
2. When leaving desk, run /teleport
3. Continue from https://claude.ai/code
4. Or check in from Claude iOS app
5. Resume locally: claude --resume <session-id>

Long-Running Autonomous Sessions (Ralph Loop)

For tasks that need extended autonomous work without intervention:

Step 1: Create worktree

spin up worktree for feature/big-refactor

Step 2: Start ralph loop in worktree terminal

/ralph-loop "Implement complete auth system with tests" --max-iterations 10

Step 3: Set completion promise (optional)

/ralph-loop "Refactor database layer" --completion-promise "All tests pass and no type errors"

How Ralph Loop Works:

• Claude works on the task
• When it tries to exit, the SAME PROMPT is fed back
• Claude sees previous work in files and git history
• Iterates until completion promise is met or max iterations reached
• Use with --dangerously-skip-permissions for fully autonomous operation

Verification Integration:

/ralph-loop "Implement feature X" --completion-promise "verify-app returns OVERALL: PASS"

Terminal Strategy

Daily Workflow Protocol

Morning:

# 1. Check worktree status
cat ~/.claude/worktree-registry.json | jq '.worktrees[] | select(.status == "active")'

# 2. Review web sessions at https://claude.ai/code

# 3. Start primary session
cd ~/tk_projects/<priority-project>
claude --model opus

Parallel Work:

# Spin up 3 worktrees with iTerm2 tabs
spin up worktrees for feature/a, feature/b, feature/c --terminal iterm2

# Or use Ghostty for quick sessions
spin up worktree for fix/quick-bug --terminal ghostty

End of Day:

# Check merged PRs
gh pr list --state merged --author @me --limit 10

# Cleanup merged worktrees
cleanup merged worktrees