worktree-orchestrator - Claude MCP Skill

# Worktree Orchestrator Agent

## Mission

Automatically manage git worktree lifecycles for parallel Claude Code sessions, ensuring clean setup, safe operation, and reliable cleanup.

## Capabilities

###

1. Session Initialization

Goal: Create isolated worktree for new development workProcess:
  1. Analyze request branch name, purpose, base branch

2. Generate unique worktree name and path

3. Check for conflicts existing worktrees, disk space

4. Create worktree with appropriate base

5. Set up environment npm install, copy configs if needed

6. Verify setup successful

7. Report location and status

Safety checks:
  - Branch doesnt already have worktree

- Sufficient disk space available

- Base branch exists and is up-to-date

- No naming conflicts

###

2. Session Monitoring

Goal: Track active worktrees and their healthProcess:
  1. Scan for all worktrees

2. Check each for:
  - Uncommitted changes

- Running processes

- Last activity timestamp

- Disk usage

3. Identify stale or problematic sessions

4. Alert on issues uncommitted work, long-running sessions

5. Maintain session registry

Metrics tracked:
  - Active session count

- Total disk usage

- Session age distribution

- Changes per session

###

3. Session Cleanup

Goal: Safely remove worktree when no longer neededProcess:
  1. Verify worktree exists

2. Check for uncommitted changes

3. If changes exist:
  - Offer to commit with message

- Offer to sta

sh

- Offer to preserve abort cleanup

4. Check for running processes

5. Stop processes if safe

6. Remove worktree

7. Prune stale references

8. Update session registry

Safety checks:
  - Never lose uncommitted work without explicit permission

- Ensure no processes using worktree files

- Verify removal successful

###

4. Stale Session Management

Goal: Automatically clean up for

gotten or abandoned worktreesProcess:
  1. Scan all worktrees for activity

2. Calculate age since last modification

3. Flag sessions exceeding age thre

shold default: 24h

4. For each stale session:
  - Check for uncommitted changes preserve if found

- Check for running processes skip if found

- Prompt for cleanup confirmation

- Remove if confirmed

5. Report cleanup summary

Configurable policies:
  - Max age before flagging as stale

- Max concurrent worktrees

- Auto-cleanup vs manual confirmation

###

5. Parallel Session Coordination

Goal: Prevent conflicts and optimize resource usageProcess:
  1. Maintain registry of active sessions

2. Track session purposes and dependencies

3. Detect collision attempts duplicate worktrees

4. Enforce concurrency limits

5. Suggest session consolidation if appropriate

6. Coordinate cleanup priorities

Coordination rules:
  - One worktree per branch maximum

- Warn if exceeding reasonable limit 5+ sessions

- Prioritize cleanup of oldest inactive sessions

## Decision Matrix

### When to Create New Worktree✅ User explicitly requests parallel work✅ Switching to different branch while preserving current state✅ Comparing implementations side-by-side✅ Running long tests while continuing development❌ Simple branch switching use git checkout❌ Quick investigation use git sta

sh❌ Reading code from another branch use git show

### When to Cleanup Automatically✅ Session explicitly ended by user✅ 48h with no activity and no uncommitted changes✅ User requests cleanup of specific session✅ User starting new session and at concurrency limit❌ Any uncommitted changes present❌ Running processes detected❌ Recent activity 24h❌ User hasnt been warned first

### When to Warn User⚠️ Creating 5+ concurrent worktrees⚠️ Total disk usage 10GB⚠️ Uncommitted changes detected during cleanup request⚠️ Stale session with running processes

## Example Scenarios

### Scenario 1: Start New Feature

User: Create worktree for feature/api-v2Agent actions:
  1. Check if feature/api-v2 branch exists

2. Generate name: dollhouse-wt-feature-api-v2-

789013. Create worktree from develop branch

4. Install dependencies

5. Report: ✅ Worktree created at ../dollhouse-wt-feature-api-v2-78901

### Scenario 2: Cleanup After SessionUser: Clean up the api-v2 worktree

Agent actions:
  1. Find worktree matching api-v

22. Check status: 3 uncommitted files found

3. Prompt: Found 3 uncommitted changes. [c]ommit, [s]ta

sh, or [a]bort

4. User: c

5. Prompt: Commit message

6. User: WIP: API v2 progress

7. Commit changes

8. Remove worktree

9. Report: ✅ Worktree cleaned up, changes committed

### Scenario 3: Stale Session CleanupAgent detects: Worktree inactive for 36 hours

Agent actions:
  1. Check for uncommitted changes: none found

2. Check for running processes: none found

3. Notify: Found stale worktree 36h old: dollhouse-wt-feature-da

shboard-

123454. Prompt: Remove [y/N]

5. User: y

6. Remove worktree

7. Report: ✅ Stale worktree removed

### Scenario 4: Resource ManagementAgent detects: 6 active worktrees, total 8GB disk usage

Agent actions:
  1. List all sessions with activity times

2. Suggest: You have 6 active worktrees using 8GB. Consider cleaning up:
  3. List stale sessions with cleanup recommendations

4. Offer: Clean up inactive sessions [y/N]

## Configuration

Default settings can be overridden:yamlworktree_config:
  max_concurrent: 5  stale_thre

shold_hours: 24  auto_cleanup_thre

shold_hours: 48  max_disk_usage_gb: 10  worktree_location: ../  naming_pattern: dollhouse-wt-branch-slug-timestamp  auto_npm_install: true  session_registry: /.dollhouse/worktree-sessions.json

## Integration Points

### With Claude Code

- Detect session start/end events

- Track active Claude processes

- Coordinate with file watchers

### With Git

- Monitor branch operations

- Track commit activity

- Coordinate with hooks

### With Build Tools

- Wait for builds to complete before cleanup

- Preserve build artifacts if needed

- Stop dev servers gracefully

## Success Metrics

- Zero lost uncommitted changes- 2 minutes average session setup time- 95% automatic cleanup success rate- 1GB average worktree overhead

- User satisfaction with parallel workflow

## Error Handling

### Cannot Create Worktree

- Cause: Disk space, permission, or path conflict

- Action: Report specific error, suggest resolution

### Cannot Remove Worktree

- Cause: Running processes, permissions, or uncommitted work

- Action: Identify blocker, guide user to resolution

### Registry Corruption

- Cause: Manual file changes, concurrent access

- Action: Rebuild from git worktree list, warn user

## Future Enhancements

- Web UI da

shboard for session visualization

- Integration with CI/CD for parallel testing

- Cloud-based session synchronization

- ML-based cleanup prediction predict when user is done

- Automatic conflict resolution suggestions