--- model: claude-sonnet-4-5-20250929 description: Create a git worktree with isolated configuration for parallel development argument-hint: [branch-name] [port-offset] allowed-tools: Bash, Read, Write, Edit, Glob, Grep --- # Purpose Create a new git worktree in the `trees/` directory with completely isolated configuration for parallel execution. This enables running multiple instances of the observability system simultaneously without port conflicts, database collisions, or hook misconfiguration. ## Variables ``` PROJECT_CWD: . (current working directory - the main project root) BRANCH_NAME: $1 (required) PORT_OFFSET: $2 (optional, defaults to auto-calculated based on existing worktrees, starts at 1) WORKTREE_BASE_DIR: trees/ WORKTREE_DIR: trees/ SERVER_BASE_PORT: 4000 CLIENT_BASE_PORT: 5173 SERVER_PORT: 4000 + (PORT_OFFSET * 10) # First worktree: 4010, Second: 4020, etc. CLIENT_PORT: 5173 + (PORT_OFFSET * 10) # First worktree: 5183, Second: 5193, etc. OPEN_BROWSER_WHEN_COMPLETE: false # Set to true to auto-open browser after setup NOTE: Main repo uses ports 4000 and 5173 (no offset) Worktrees start at offset 1 to avoid conflicts with main repo ``` ## Instructions - This is a ONE-SHOT command that creates AND starts a worktree automatically - Creates a fully functional, isolated clone of the codebase in a separate worktree - Each worktree runs on unique ports to prevent conflicts when running in parallel - Port offsets start at 1 and increment (1→4010/5183, 2→4020/5193, 3→4030/5203...) - Main repo preserves default ports 4000/5173 for primary development work - All environment configuration must be worktree-specific - Database files are isolated per worktree (each gets its own events.db) - Hook scripts will send events to the worktree's specific server instance - Dependencies are installed automatically for each worktree - After setup, the script automatically starts both server and client services - The start script kills any existing processes on the target ports before starting - Services run in the FOREGROUND - Ctrl+C stops both server and client - Validation ensures the worktree is ready before starting services - If branch doesn't exist locally, create it from current HEAD - If branch exists but isn't checked out, create worktree from it - Provide clear access URLs so user can immediately use the running instance ## Workflow ### 1. Parse and Validate Arguments - Read BRANCH_NAME from $1, error if missing - Read PORT_OFFSET from $2 if provided - If PORT_OFFSET not provided, calculate next available offset: - List all existing worktrees: `git worktree list` - Check PROJECT_CWD/trees/ directory for existing worktrees - Count existing worktrees and use (count + 1) as offset (1, 2, 3, 4...) - IMPORTANT: Offset starts at 1 to preserve main repo ports (4000, 5173) - First worktree gets offset 1 → ports 4010, 5183 - Second worktree gets offset 2 → ports 4020, 5193 - Calculate SERVER_PORT and CLIENT_PORT using offset * 10 - Validate branch name format (no spaces, valid git branch name) ### 2. Pre-Creation Validation - Check if PROJECT_CWD/trees/ directory exists, create if not: `mkdir -p trees` - Verify trees/ is in PROJECT_CWD/.gitignore (should be there already) - Check if worktree already exists at WORKTREE_DIR - Check if branch exists: `git branch --list ` - If branch doesn't exist, will create it in next step - If branch exists, will checkout to create worktree - Check if calculated ports are available: - Check SERVER_PORT: `lsof -i :SERVER_PORT` (should return nothing) - Check CLIENT_PORT: `lsof -i :CLIENT_PORT` (should return nothing) - If ports are in use, error with message to try different offset ### 3. Create Git Worktree - From PROJECT_CWD, create worktree with: `git worktree add trees/ ` - If branch doesn't exist, this creates it from HEAD - If branch exists, this checks it out in the worktree - This creates WORKTREE_DIR at PROJECT_CWD/trees/ - Verify worktree was created: `git worktree list | grep trees/` - All subsequent operations will reference WORKTREE_DIR (which is PROJECT_CWD/trees/) ### 4. Setup Root Environment File - Check if root .env exists in main project at PROJECT_CWD/.env - If PROJECT_CWD/.env exists: - Copy it to worktree root: `cp /.env /.env` - Note: This preserves API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) - If PROJECT_CWD/.env doesn't exist: - Copy .env.sample if available: `cp /.env.sample /.env` - Add warning to report that user needs to configure API keys ### 5. Setup Server Environment - Create WORKTREE_DIR/apps/server/.env with SERVER_PORT and DB_PATH - File contents: ``` SERVER_PORT= DB_PATH=events.db ``` - The DB_PATH is relative and will create events.db in WORKTREE_DIR/apps/server/ directory - This ensures complete database isolation between worktrees ### 6. Setup Client Environment - Create WORKTREE_DIR/apps/client/.env with all client configuration - File contents: ``` VITE_PORT= VITE_API_URL=http://localhost: VITE_WS_URL=ws://localhost:/stream VITE_MAX_EVENTS_TO_DISPLAY=100 OBSERVABILITY_SERVER_URL=http://localhost:/events ``` - The OBSERVABILITY_SERVER_URL is critical for hooks to send events to correct server ### 7. Install Dependencies - Install server dependencies: - `cd /apps/server && bun install` - Verify WORKTREE_DIR/apps/server/node_modules directory was created - Install client dependencies: - `cd /apps/client && bun install` - Verify WORKTREE_DIR/apps/client/node_modules directory was created - Return to worktree root: `cd ` ### 8. Validation - Verify directory structure: - Confirm WORKTREE_DIR exists - Confirm WORKTREE_DIR/.env exists at root - Confirm WORKTREE_DIR/apps/server/.env exists - Confirm WORKTREE_DIR/apps/client/.env exists - Confirm WORKTREE_DIR/apps/server/node_modules exists - Confirm WORKTREE_DIR/apps/client/node_modules exists - List worktrees to confirm: `git worktree list` - Read back the created env files to confirm values are correct ### 9. Start the Worktree Services - Change to worktree directory: `cd ` - Start the system using the one-shot script in the BACKGROUND: - Command: `cd && SERVER_PORT= CLIENT_PORT= sh scripts/start-system.sh > /dev/null 2>&1 &` - This runs WORKTREE_DIR/scripts/start-system.sh in background, redirecting output to suppress it - The script will automatically: - Kill any existing processes on those ports - Start the server from WORKTREE_DIR/apps/server on the calculated port - Start the client from WORKTREE_DIR/apps/client on the calculated port - Wait for both services to be ready (health check) - Give services 3-5 seconds to start before reporting - Wait with: `sleep 5` - Verify services are running: - Check server: `curl -s http://localhost:/events/filter-options >/dev/null 2>&1` - Check client: `curl -s http://localhost: >/dev/null 2>&1` - If health checks pass, services are confirmed running ### 10. Open Dashboard in Chrome (Optional) - ONLY if OPEN_BROWSER_WHEN_COMPLETE is true: - After services are confirmed running, open the dashboard in Chrome: - Command: `open -a "Google Chrome" http://localhost:` - This automatically opens the worktree's dashboard in a new Chrome tab - If Chrome is not available, fall back to default browser: `open http://localhost:` - Note: This happens in the background and doesn't block the report - If OPEN_BROWSER_WHEN_COMPLETE is false, skip this step entirely ### 11. Report Follow the Report section format below to provide comprehensive setup information. ## Report After successful worktree creation, validation, and startup, provide a detailed report in the following format: ``` ✅ Git Worktree Created and Started Successfully! 📁 Worktree Details: Location: trees/ Branch: Status: 🟢 RUNNING 🔌 Port Configuration: Server Port: Client Port: Port Offset: (multiply by 10) 🌐 Access URLs (LIVE NOW): 🖥️ Dashboard: http://localhost: 🔌 Server API: http://localhost: 📡 WebSocket: ws://localhost:/stream 📦 Dependencies: ✓ Server dependencies installed (WORKTREE_DIR/apps/server/node_modules) ✓ Client dependencies installed (WORKTREE_DIR/apps/client/node_modules) 🗄️ Database: Path: WORKTREE_DIR/apps/server/events.db (isolated per worktree) ⚙️ Environment Files: ✓ Root .env (WORKTREE_DIR/.env with API keys) ✓ Server .env (WORKTREE_DIR/apps/server/.env with SERVER_PORT, DB_PATH) ✓ Client .env (WORKTREE_DIR/apps/client/.env with VITE_PORT, API URLs) 🎯 Services Running: ✓ Server started on port (background) ✓ Client started on port (background) ✓ WebSocket streaming active ✓ Ready to receive hook events 📝 Important Notes: • The services are running in the BACKGROUND • Services auto-started and will continue running until manually stopped • Open http://localhost: in your browser NOW to view the dashboard • This worktree is completely isolated from the main codebase • You can run multiple worktrees simultaneously with different ports • Check running processes: lsof -i : and lsof -i : 🔄 To Restart This Worktree Later: cd trees/ # Kill existing processes first lsof -ti : | xargs kill -9 lsof -ti : | xargs kill -9 # Or use the one-shot script (it kills automatically) SERVER_PORT= CLIENT_PORT= sh scripts/start-system.sh > /dev/null 2>&1 & 🧹 To Stop This Worktree: # Option 1: Manual kill lsof -ti : | xargs kill -9 lsof -ti : | xargs kill -9 # Option 2: Use reset script (with environment variables) cd trees/ SERVER_PORT= CLIENT_PORT= ./scripts/reset-system.sh 🗑️ To Remove This Worktree: # Stop services first (see above) # Then remove the worktree: git worktree remove trees/ # Or force remove if needed: git worktree remove trees/ --force 🎉 Next Steps: 1. Open http://localhost: in your browser NOW 2. Open Claude Code in this worktree directory 3. Run commands - events will stream to this isolated instance 4. Compare side-by-side with other worktrees or main codebase 5. Each instance maintains its own database and event history ``` If any validation steps failed or warnings occurred, include an additional section: ``` ⚠️ Warnings / Action Required: - ```