Worktree Management Skill

Purpose

This skill automates Git worktree creation and management for parallel development workflows. It provides isolated development environments with:

• Automatic Git worktree and branch creation
• Auto-incrementing port allocation for Docker services
• Isolated browser MCP servers (Playwright, Chrome DevTools, Puppeteer)
• Automatic .env file copying from main project
• Docker Compose configuration extension
• Worktree state tracking and lifecycle management
• Port conflict detection and resolution

When to Use This Skill

Use this skill when:

• Creating isolated development environments for feature branches
• Running parallel development sessions without port conflicts
• Testing features independently with isolated Docker services
• Managing multiple worktrees across a project
• Cleaning up and removing worktrees safely

Core Commands

Create Worktree

@worktree create <name> [--branch=<branch-name>] [--start-services]

Creates a new Git worktree with isolated services. The process:

1. Validates worktree name and checks for conflicts
2. Allocates unique ports (auto-incremented from existing worktrees)
3. Creates Git worktree and branch
4. Copies .env files from main project (backend/.env, frontend/.env, .env)
5. Configures CORS for worktree frontend port - Updates both backend/.env ALLOWED_ORIGINS and backend/config/initializers/cors.rb to include the worktree's frontend port
6. Creates isolated browser data directory (.browser-data/)
7. Generates .mcp.json with browser isolation configuration
8. Generates docker-compose.worktree.yml extending main config
9. Creates start-worktree.sh startup script
10. Updates .gitignore to exclude .gitignore and .mcp.json files (prevents committing worktree-specific configs)
11. Updates worktree tracking registry
12. Optionally starts Docker services
13. Provides next-step instructions for Claude Code launch

Examples:

@worktree create feature-user-export
@worktree create bugfix-email --branch=bugfix/email-preview-fix
@worktree create docs-api --branch=docs/api-documentation --start-services

List Worktrees

@worktree list [--status]

Shows all active worktrees with name, path, branch, allocated ports, Docker service status, and created timestamp.

Switch to Worktree

@worktree switch <name>

Provides instructions to change directory, check service status, and launch Claude Code instance.

Start/Stop Services

@worktree start <name>
@worktree stop <name>

Starts or stops Docker services for specified worktree.

Remove Worktree

@worktree remove <name> [--delete-branch] [--force]

Safely removes worktree with cleanup:

1. Stops Docker services if running
2. Removes worktree directory
3. Optionally deletes Git branch
4. Frees allocated ports
5. Updates tracking registry

Flags:

• --delete-branch: Delete the Git branch after removal
• --force: Skip confirmation prompts

Check Status

@worktree status <name>

Shows detailed status including Git branch/commit info, Docker service status, port allocations, and uncommitted changes warnings.

Show Port Allocations

@worktree ports [<name>]

Shows port allocations for specific worktree or all worktrees.

Sync from Main Branch

@worktree sync <name>

Updates worktree branch from development/main by fetching latest and rebasing.

Implementation Details

Port Allocation Strategy

Auto-increment approach:

• Scans existing worktrees for highest port numbers
• Increments by 1 for each new worktree
• Maintains port registry to prevent conflicts
• Intelligently scans up to 50 sequential ports to find available ones

Port ranges:

• Backend: 3000 (main), 3001+ (worktrees)
• Frontend: 4000 (main), 4001+ (worktrees)
• Database: 5433 (main), 5434+ (worktrees)
• Playwright: 9223 (main), 9224+ (worktrees)
• Chrome DevTools: 9222 (main), 9223+ (worktrees)
• Puppeteer: 9224 (main), 9225+ (worktrees)

Port conflict prevention:

• Pre-flight validation checks all ports before Docker startup
• Detects conflicts from main project, other worktrees, or system processes
• Provides detailed conflict report with resolution options
• Graceful degradation: worktree creation succeeds even with port conflicts (services startup deferred)

For detailed port allocation documentation, see references/port-allocation.md.

Browser Isolation

Each worktree gets its own Docker-based browser automation services with complete isolation:

Docker Services Created:

• chrome-devtools-mcp-{worktree-name}: Headless Chrome for DevTools Protocol automation
• Each service uses a named Docker volume for persistent browser data
• Unique container names prevent conflicts between worktrees

Chrome DevTools MCP Configuration:

chrome-devtools-mcp:
  container_name: chrome-devtools-mcp-{worktree-name}
  ports:
    - "{allocated-port}:9222"
  volumes:
    - chrome_devtools_data_{worktree-name}:/data

MCP Server Configuration: Each worktree's .mcp.json is automatically configured to use its own Chrome DevTools container:

{
  "chrome-devtools": {
    "command": "docker",
    "args": ["exec", "-i", "chrome-devtools-mcp-{worktree-name}", ...],
    "env": {
      "CHROME_USER_DATA_DIR": "/data",
      "CHROME_REMOTE_DEBUGGING_PORT": "9222"
    }
  }
}

Benefits:

• Run browser automation in multiple worktrees simultaneously
• Complete isolation of browser state, cookies, and sessions
• No container name conflicts - each worktree has unique container
• Independent debugging ports for each worktree
• Persistent browser data across container restarts

Technical Details:

• Internal port is always 9222 (Chrome debugging protocol standard)
• External port is auto-allocated (9222 for main, 9223+ for worktrees)
• Docker port mapping handles external isolation: {external}:9222
• Each worktree's Claude Code instance connects to its own container

For detailed browser isolation information, see references/browser-isolation.md.

Docker Compose Strategy

Each worktree generates a standalone docker-compose.worktree.yml file (does NOT extend main docker-compose.yml).

Services included:

• backend-{worktree-name}: Rails API server with unique port
• frontend-{worktree-name}: React dev server with unique port
• db-{worktree-name}: PostgreSQL database with unique port
• chrome-devtools-mcp-{worktree-name}: Headless Chrome for browser automation
• redis-{worktree-name}: Redis (disabled by default for development)

Key Features:

• Each service has worktree-specific container name
• Unique port mappings prevent conflicts
• Named Docker volumes for data persistence
• Environment variables configured per worktree

Usage:

cd /path/to/worktree
docker-compose -f docker-compose.worktree.yml up
# Or use the convenience script:
./start-worktree.sh

For detailed Docker strategy documentation, see references/docker-strategy.md.

Environment File Management

Automatically copies and configures environment files from main project to each worktree:

• backend/.env → Copied to worktree's backend directory (CORS configured)
• frontend/.env → Copied and updated with worktree backend port
• frontend/.env.development → Copied and updated with worktree backend port
• .env (root) → Copied to worktree root (ports updated)

Critical Frontend Configuration: The skill automatically updates VITE_API_BASE_URL in both frontend/.env and frontend/.env.development to point to the worktree's backend port. This ensures proper frontend-backend isolation between worktrees.

Example:

• Main project: VITE_API_BASE_URL=http://localhost:3000/api/v1
• Worktree 1: VITE_API_BASE_URL=http://localhost:3001/api/v1
• Worktree 2: VITE_API_BASE_URL=http://localhost:3002/api/v1

This prevents Docker service startup failures due to missing gitignored files and ensures each worktree's frontend communicates with its own backend instance.

CORS Configuration

Automatic CORS setup for worktree frontend port:

When creating a worktree, the skill automatically configures CORS to allow the worktree's frontend port:

1. Updates backend/.env: Adds the worktree frontend port (e.g., http://localhost:4004) to the ALLOWED_ORIGINS environment variable
2. Updates cors.rb: Adds the worktree frontend port to the development defaults array in backend/config/initializers/cors.rb

Why this matters:

• Prevents CORS errors when the frontend tries to communicate with the backend API
• Ensures login, API calls, and authentication work immediately without manual configuration
• Each worktree gets its frontend port automatically whitelisted

Example: For a worktree with frontend port 4004, both files will include http://localhost:4004:

• .env: ALLOWED_ORIGINS=http://localhost:4000,...,http://localhost:4004
• cors.rb: allowed_origins = ["http://localhost:4000", ..., "http://localhost:4004"]

For detailed CORS configuration documentation, see references/cors-configuration.md.

Worktree-Specific Git Configuration

Each worktree automatically configures its .gitignore to exclude worktree-specific files:

• .gitignore itself - Prevents worktree's customized gitignore from being committed
• .mcp.json - Prevents worktree's browser isolation config from being committed

Purpose:

• Keeps worktree-specific configurations isolated
• Prevents accidental merge of worktree configs back to main branch
• Maintains clean separation between worktree and main project settings

Implementation: The skill appends these entries to the worktree's .gitignore during creation:

# Worktree-specific files (do not commit)
.gitignore
.mcp.json

State Tracking

Worktree Registry (worktrees.json): Tracks all worktrees with name, path, branch, creation timestamp, port allocations, status, and Docker service state.

Port Registry (port-registry.json): Maintains allocated ports to prevent conflicts.

Using the Skill

Typical Development Workflow

# 1. Create worktree with services
@worktree create feature-auth --start-services

# 2. Switch to worktree (in new terminal)
cd /path/to/worktree
claude

# 3. Develop in isolated environment
# - Separate conversation history
# - Independent browser automation
# - No port conflicts

# 4. When done, merge back
cd /path/to/main/project
git checkout development
git merge feature/auth

# 5. Keep worktree for reuse or remove
@worktree remove feature-auth

Accessing Bundled Resources

Scripts (scripts/):

• worktree-manager.sh - Main worktree management script with all commands

Templates (assets/):

• docker-compose.worktree.template.yml - Docker Compose extension template
• mcp.template.json - MCP configuration template with browser isolation
• start-worktree.template.sh - Service startup script template

References (references/):

• port-allocation.md - Detailed port allocation documentation
• browser-isolation.md - Browser MCP isolation details
• docker-strategy.md - Docker Compose extension pattern
• cors-configuration.md - CORS auto-configuration details
• troubleshooting.md - Common issues and solutions

State Files (skill root):

• worktrees.json - Worktree registry (auto-managed)
• port-registry.json - Port allocations (auto-managed)

To execute worktree commands, invoke the main script:

~/.claude/skills/worktree-management/scripts/worktree-manager.sh <command> [args]

Best Practices

1. Name worktrees descriptively: Use clear names like feature-auth, bugfix-email, docs-api
2. Use branch naming conventions: Auto-converts feature-auth → feature/auth
3. Verify .env files exist: Ensure main project has .env files before creating worktrees
4. Start services explicitly: Use --start-services flag or run manually after resolving conflicts
5. Stop services when done: Free resources with @worktree stop <name>
6. Sync regularly: Stay updated with @worktree sync <name>
7. Keep worktrees for reuse: Don't remove unless completely done with feature
8. Check status before merge: View uncommitted changes with @worktree status <name>
9. Browser isolation works automatically: No manual configuration needed for parallel testing
10. Worktree configs stay isolated: .gitignore and .mcp.json automatically excluded from commits

Safety Features

• Pre-creation validation (name conflicts, port availability)
• Pre-removal validation (uncommitted changes, running services)
• Rollback on failed operations
• Port registry prevents conflicts
• State tracking enables recovery
• Confirmation prompts for destructive operations
• Automatic .env file copying prevents Docker failures
• Automatic CORS configuration prevents authentication and API errors
• Browser isolation prevents session conflicts
• Automatic .gitignore configuration prevents accidental commit of worktree-specific files

Limitations

• Claude Code launch: Instruction-based only (can't auto-launch new instance)
• Manual cleanup: Worktrees kept indefinitely (manual removal required)
• No automatic sync: Must manually sync from development branch
• Port exhaustion: No automatic cleanup of unused port allocations
• .env file changes: Updates to main project .env not auto-synced to worktrees

Troubleshooting

For detailed troubleshooting guidance, see references/troubleshooting.md.

Quick Solutions

Port conflicts:

@worktree ports                    # Check allocations
@worktree stop <name>             # Free ports

Docker services won't start:

# Stop main project services
cd /path/to/main/project
docker-compose down

Missing .env files:

# Copy manually if automatic copying failed
cp /path/to/main/backend/.env ./backend/.env
cp /path/to/main/frontend/.env ./frontend/.env

Recent Bug Fixes

Critical: Worktree Removal Bug (FIXED - 2025-10-22)

Issue: Removing a worktree accidentally removed ALL Docker containers, including main project containers.

Root Cause: Removal script used docker-compose down with both main and worktree compose files.

Fix: Removed docker-compose down command. Now uses only targeted container removal by name, which is safe and isolated.

Impact: No longer affects main project containers when removing worktrees.