zhongwei/gh-djacobsmeyer-claude-skills-engineering-plugins-manage-worktrees-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:22:09 +08:00
commit 6fc9ce7847
11 changed files with 1570 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "manage-worktrees-skill",
"description": "Comprehensive git worktree management for creating, listing, and removing worktrees. Use when the user wants to create new development environments, view worktree status, or manage the lifecycle of parallel development environments. Provides slash commands /create_worktree, /list_worktrees, and /remove_worktree.",
"version": "1.0.0",
"author": {
"name": "Don Jacobsmeyer",
"email": "hello@donjacobsmeyer.com"
},
"commands": [
"./commands"
],
"skills": [
"./"
]
}

169
EXAMPLES.md Normal file
View File

@@ -0,0 +1,169 @@
# Worktree Usage Examples
Real-world examples demonstrating how to handle different worktree management scenarios.
## Example 1: Create a new worktree
**User says:** "Create a worktree for the feature-authentication branch"
**Your action:**
1. Use SlashCommand: `/create_worktree feature-authentication`
2. Share the output showing access URLs and ports
**Result:** New worktree created at `trees/feature-authentication` with services running
**Sample response to user:**
> I've created a new worktree for the `feature-authentication` branch. It's running at:
> - Dashboard: http://localhost:5183/dashboard
> - Server: http://localhost:4010
> - Client: http://localhost:5183
---
## Example 2: Create with specific port offset
**User says:** "Set up a parallel environment on branch hotfix-security with port offset 3"
**Your action:**
1. Use SlashCommand: `/create_worktree hotfix-security 3`
2. Share output (will use ports 4030, 5203)
**Result:** Worktree created with custom ports
**Sample response to user:**
> Created worktree for `hotfix-security` with port offset 3:
> - Server: http://localhost:4030
> - Client: http://localhost:5203
---
## Example 3: List all worktrees
**User says:** "What worktrees do I have?"
**Your action:**
1. Use SlashCommand: `/list_worktrees`
2. Share the comprehensive overview
**Result:** User sees all worktrees with their configuration and status
---
## Example 4: Check worktree status
**User says:** "Show me the status of my worktrees"
**Your action:**
1. Use SlashCommand: `/list_worktrees`
2. Highlight key information: running services, ports in use, access URLs
**Result:** User sees which worktrees are active and their details
**What to highlight:**
- Which services are running vs stopped
- Port conflicts if any
- Quick access URLs
- PIDs of running processes
---
## Example 5: Remove a worktree
**User says:** "Delete the feature-auth worktree"
**Your action:**
1. Use SlashCommand: `/remove_worktree feature-auth`
2. Confirm removal completed
**Result:** Worktree removed, services stopped, directory cleaned up
**Sample response to user:**
> Successfully removed the `feature-auth` worktree:
> - Stopped all running services
> - Cleaned up directories
> - Worktree has been removed
---
## Example 6: Remove with different wording
**User says:** "Clean up the old-branch worktree, I don't need it anymore"
**Your action:**
1. Use SlashCommand: `/remove_worktree old-branch`
2. Share confirmation
**Result:** Worktree removed successfully
**Note:** Recognize variations: "clean up", "don't need", "remove", "delete" all indicate removal.
---
## Example 7: Multiple operations workflow
**User says:** "Show me my worktrees, then create a new one for refactor-api"
**Your action:**
1. Use SlashCommand: `/list_worktrees`
2. Share current worktrees
3. Use SlashCommand: `/create_worktree refactor-api`
4. Share new worktree details
**Result:** User sees existing worktrees, then gets a new one created
**Sample response to user:**
> Here are your current worktrees:
> [list output]
>
> Now creating a new worktree for `refactor-api`...
> [creation output with URLs]
---
## Example 8: Managing parallel environments
**User says:** "I need three worktrees for branches: feature-a, feature-b, and feature-c"
**Your action:**
1. Use SlashCommand: `/create_worktree feature-a`
2. Use SlashCommand: `/create_worktree feature-b`
3. Use SlashCommand: `/create_worktree feature-c`
4. Use SlashCommand: `/list_worktrees` (to show all three)
**Result:** Three parallel worktrees created with unique ports
**Sample response to user:**
> Created three worktrees for parallel development:
>
> 1. **feature-a**
> - Server: http://localhost:4010
> - Client: http://localhost:5183
>
> 2. **feature-b**
> - Server: http://localhost:4020
> - Client: http://localhost:5193
>
> 3. **feature-c**
> - Server: http://localhost:4030
> - Client: http://localhost:5203
>
> All services are running and ready for development!
---
## Pattern Recognition
### Create Keywords
- "create", "new", "setup", "make", "build", "start", "initialize"
- "I need a worktree for..."
- "Set up a parallel environment..."
### List Keywords
- "list", "show", "display", "what", "which", "status", "check", "view"
- "What worktrees do I have?"
- "Show me my environments..."
### Remove Keywords
- "remove", "delete", "cleanup", "destroy", "stop", "kill", "terminate"
- "Clean up the...", "I don't need..."
- "Get rid of...", "Delete the..."

86
OPERATIONS.md Normal file
View File

@@ -0,0 +1,86 @@
# Worktree Operations Guide
Detailed step-by-step instructions for each worktree operation.
## CREATE Operations
**When user wants to create a worktree:**
### Step 1: Extract information
- **Branch name** (required) - The git branch to create the worktree from
- **Port offset** (optional) - Custom port offset, defaults to auto-calculated
### Step 2: Invoke command
```
/create_worktree <branch-name> [port-offset]
```
### Step 3: What happens automatically
The command handles:
- Creates git worktree in `trees/<branch-name>`
- Configures unique ports (auto-calculated if offset not provided)
- Sets up all environment files (.env, .claude/settings.json)
- Installs dependencies (npm/bun install)
- Starts services in background (server + client)
- Provides access URLs
### Step 4: Share results with user
Include:
- Dashboard URL (e.g., http://localhost:5183/dashboard)
- Configured ports (server + client)
- How to access the running services
- Location of worktree directory
---
## LIST Operations
**When user wants to see worktrees:**
### Step 1: Invoke command
```
/list_worktrees
```
### Step 2: What the command shows
The output includes:
- All existing worktrees with their paths
- Port configuration for each (server + client)
- Service status (running/stopped with PIDs)
- Access URLs for each worktree
- Quick action commands for management
### Step 3: Share the overview with user
Highlight:
- Which worktrees are currently running
- How to access each one
- Any issues or conflicts
---
## REMOVE Operations
**When user wants to remove a worktree:**
### Step 1: Extract information
- **Branch name** (required) - The name of the worktree to remove
### Step 2: Invoke command
```
/remove_worktree <branch-name>
```
### Step 3: What happens automatically
The command handles:
- Stops running services (server + client)
- Kills processes on worktree ports
- Removes git worktree
- Cleans up directories
- Validates complete removal
- Reports success or any issues
### Step 4: Confirm removal with user
Share:
- Confirmation that worktree was removed
- Services that were stopped
- Any cleanup actions performed

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# manage-worktrees-skill
Comprehensive git worktree management for creating, listing, and removing worktrees. Use when the user wants to create new development environments, view worktree status, or manage the lifecycle of parallel development environments. Provides slash commands /create_worktree, /list_worktrees, and /remove_worktree.

270
REFERENCE.md Normal file
View File

@@ -0,0 +1,270 @@
# Worktree Quick Reference
Technical details, command syntax, and configuration reference.
## Command Syntax
### Create Worktree
```bash
/create_worktree <branch-name> [port-offset]
```
**Parameters:**
- `branch-name` (required) - Name of the git branch
- `port-offset` (optional) - Port offset number (default: auto-calculated)
**Example:**
```bash
/create_worktree feature-auth
/create_worktree hotfix-bug 3
```
---
### List Worktrees
```bash
/list_worktrees
```
**Parameters:** None
**Output includes:**
- Worktree paths
- Port configurations
- Service status with PIDs
- Access URLs
- Quick commands
---
### Remove Worktree
```bash
/remove_worktree <branch-name>
```
**Parameters:**
- `branch-name` (required) - Name of the worktree to remove
**Example:**
```bash
/remove_worktree feature-auth
```
---
## Port Allocation
### Port Calculation Formula
```
SERVER_PORT = 4000 + (offset * 10)
CLIENT_PORT = 5173 + (offset * 10)
```
### Port Map
| Environment | Offset | Server Port | Client Port |
|-------------|--------|-------------|-------------|
| Main Repo | 0 | 4000 | 5173 |
| Worktree 1 | 1 | 4010 | 5183 |
| Worktree 2 | 2 | 4020 | 5193 |
| Worktree 3 | 3 | 4030 | 5203 |
| Worktree 4 | 4 | 4040 | 5213 |
| Worktree 5 | 5 | 4050 | 5223 |
### Auto-calculated Offsets
When no port offset is specified, the system:
1. Lists existing worktrees
2. Finds highest used offset
3. Increments by 1
4. Uses that as the new offset
---
## Directory Structure
### Main Repository
```
project/
├── .claude/
│ ├── settings.json
│ └── commands/
├── .env
├── server/
└── client/
```
### Worktree Structure
```
project/
└── trees/
└── <branch-name>/
├── .claude/
│ └── settings.json (isolated config)
├── .env (unique ports)
├── server/
└── client/
```
---
## Configuration Files
### .env (Worktree-specific)
```env
VITE_SERVER_URL=http://localhost:[SERVER_PORT]
VITE_CLIENT_PORT=[CLIENT_PORT]
SERVER_PORT=[SERVER_PORT]
```
### .claude/settings.json (Worktree-specific)
```json
{
"hooks": {
"userPromptSubmit": {
"script": "...",
"env": {
"AGENT_SERVER_URL": "http://localhost:[SERVER_PORT]"
}
}
}
}
```
---
## Service Management
### What Runs in a Worktree
1. **Server** - Backend API (Express/Node)
2. **Client** - Frontend dev server (Vite)
### Background Process Management
- Services run in detached background processes
- PIDs tracked for process management
- Automatic cleanup on removal
- Force-kill on stuck processes
### Service States
- **Running** - Process active with valid PID
- **Stopped** - No process running
- **Zombie** - PID exists but process unresponsive
---
## Git Worktree Fundamentals
### What is a Git Worktree?
A git worktree is an additional working directory attached to the same repository. Multiple worktrees can exist simultaneously, each checked out to different branches.
### Benefits
- Work on multiple branches simultaneously
- No need to stash/switch branches
- Isolated development environments
- Test multiple features in parallel
### Limitations
- Each branch can only be checked out in one worktree
- Worktrees share git history/objects
- Disk space required for each copy
---
## Isolation Features
Each worktree has:
| Feature | Isolation Level | Notes |
|---------|----------------|-------|
| **File System** | Complete | Separate working directory |
| **Ports** | Complete | Unique port allocation |
| **Configuration** | Complete | Own .env and settings.json |
| **Database** | Configurable | Can use separate DBs |
| **Dependencies** | Complete | Own node_modules |
| **Git History** | Shared | Same repository |
| **Git Config** | Shared | Same git settings |
---
## Related Capabilities
### Main Repository
- Default environment
- Uses ports 4000 and 5173
- No special setup needed
- Can run alongside worktrees
### Parallel Development
- Run main + multiple worktrees simultaneously
- Each fully isolated
- No conflicts between environments
- Test features against different bases
### Branch Preservation
- Removing a worktree doesn't delete the branch
- Branch still exists in git
- Can recreate worktree anytime
- Safe to cleanup unused worktrees
### Service Lifecycle
- Services start automatically on creation
- Run in background until removal
- Can be restarted manually if needed
- Stopped automatically on removal
---
## Best Practices
### When to Create Worktrees
✓ Testing multiple features simultaneously
✓ Reviewing PRs while working on features
✓ Hot-fixing production while developing
✓ Running integration tests in isolation
### When NOT to Create Worktrees
✗ Simple branch switching (use git checkout)
✗ Temporary file viewing (use git show)
✗ Quick edits (stash and switch)
### Cleanup Recommendations
- Remove worktrees when feature is merged
- Don't let unused worktrees accumulate
- Regular audit with `/list_worktrees`
- Free up ports for active development
### Naming Conventions
- Use descriptive branch names
- Avoid special characters
- Keep names concise
- Match branch naming scheme
---
## Technical Implementation
### Creation Process
1. Validate branch exists
2. Calculate/verify port offset
3. Create git worktree
4. Copy configuration templates
5. Update ports in configs
6. Install dependencies
7. Start services
8. Verify startup
9. Report access info
### Removal Process
1. Find processes on worktree ports
2. Kill server process
3. Kill client process
4. Remove git worktree
5. Clean up directories
6. Validate removal
7. Report results
### Status Checking
1. List git worktrees
2. Read configuration for each
3. Check if processes running
4. Verify port accessibility
5. Generate comprehensive report

72
SKILL.md Normal file
View File

@@ -0,0 +1,72 @@
---
name: worktree-manager-skill
description: Comprehensive git worktree management. Use when the user wants to create, remove, list, or manage worktrees. Handles all worktree operations including creation, deletion, and status checking.
allowed-tools: SlashCommand, Bash, Read, Write, Edit, Glob, Grep
---
# Worktree Manager Skill
Complete worktree lifecycle management for parallel development environments with isolated ports, databases, and configuration.
## When to use this skill
Use this skill when the user wants to:
- **Create** a new worktree for parallel development
- **Remove** an existing worktree
- **List** all worktrees and their status
- **Check** worktree configuration or status
- **Manage** multiple parallel development environments
**Do NOT use this skill when:**
- User asks for a specific subagent or skill delegation
- User wants to manually use git commands directly
- The task is unrelated to worktree management
## Operations Overview
This skill manages three core worktree operations:
| Operation | Command | When to Use |
|-----------|---------|-------------|
| **Create** | `/create_worktree` | User wants a new parallel environment |
| **List** | `/list_worktrees` | User wants to see existing worktrees |
| **Remove** | `/remove_worktree` | User wants to delete a worktree |
## Decision Tree: Which Command to Use
### 1. User wants to CREATE a worktree
**Keywords:** create, new, setup, make, build, start, initialize
**Action:** Use `/create_worktree <branch-name> [port-offset]`
### 2. User wants to LIST worktrees
**Keywords:** list, show, display, what, which, status, check, view
**Action:** Use `/list_worktrees`
### 3. User wants to REMOVE a worktree
**Keywords:** remove, delete, cleanup, destroy, stop, kill, terminate
**Action:** Use `/remove_worktree <branch-name>`
## Quick Start
For step-by-step operation instructions, see [OPERATIONS.md](OPERATIONS.md).
For detailed examples and usage patterns, see [EXAMPLES.md](EXAMPLES.md).
For troubleshooting and common issues, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
For technical details and quick reference, see [REFERENCE.md](REFERENCE.md).
## Important Notes
### Do NOT attempt to:
- Create worktrees manually with git commands
- Manually configure ports or environment files
- Use bash to remove directories directly
- Manage worktree processes manually
### Always use the slash commands because they:
- Handle all configuration automatically
- Ensure port uniqueness
- Validate operations
- Provide comprehensive error handling
- Clean up properly on removal

192
TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,192 @@
# Worktree Troubleshooting Guide
Common issues and their solutions when managing worktrees.
## Issue 1: "My worktree isn't working"
### Symptoms
- User can't access the worktree
- Services appear down
- URLs not responding
### Diagnosis Steps
1. Run `/list_worktrees` to check status
2. Look for service status (running/stopped)
3. Check port configuration
### Solutions
- If services are stopped, recreate the worktree
- If ports conflict, use a different port offset
- Check if processes crashed (look at PIDs)
### What to tell the user
> Let me check the status of your worktrees...
> [run /list_worktrees]
> I see the issue - [explain problem and solution]
---
## Issue 2: "I can't create a worktree"
### Symptoms
- Creation command fails
- Error messages about existing worktrees
- Port conflicts
### Common Causes
1. **Worktree already exists** - Branch already has a worktree
2. **Invalid branch name** - Branch doesn't exist in repository
3. **Port already in use** - Another service using the ports
### Solutions
1. Check existing worktrees: `/list_worktrees`
2. Verify branch exists: `git branch -a`
3. Try a different port offset if ports conflict
4. Remove old worktree first if recreating
### What to tell the user
> It looks like [diagnosis]. Let me [solution approach].
---
## Issue 3: "How do I access my worktree?"
### User doesn't know the URLs
### Solution
1. Run `/list_worktrees` to see access URLs
2. Show the Dashboard URL for their specific worktree
3. Explain the port scheme
### What to tell the user
> Here are the access URLs for your worktree:
> - Dashboard: http://localhost:[CLIENT_PORT]/dashboard
> - Server API: http://localhost:[SERVER_PORT]
> - Client: http://localhost:[CLIENT_PORT]
---
## Issue 4: "Services won't stop"
### Symptoms
- Processes still running after removal attempt
- Ports still in use
- Can't recreate worktree due to conflicts
### Solutions
1. Use `/remove_worktree` which force-kills processes
2. If still stuck, run `/list_worktrees` to see PIDs
3. Can manually kill processes if needed: `kill -9 <PID>`
### What to tell the user
> I'll use the remove command which will force-stop all services...
> [run /remove_worktree]
---
## Issue 5: "Port conflicts"
### Symptoms
- Error about port already in use
- Services fail to start
- Multiple worktrees on same ports
### Solutions
1. List existing worktrees to see port allocation
2. Use explicit port offset when creating: `/create_worktree branch-name 4`
3. Remove unused worktrees to free up ports
### Port Allocation Reference
- Main: 4000, 5173
- Offset 1: 4010, 5183
- Offset 2: 4020, 5193
- Offset 3: 4030, 5203
- Pattern: BASE + (offset * 10)
---
## Issue 6: "Worktree directory exists but not listed"
### Symptoms
- Directory in `trees/` folder
- Not showing in `/list_worktrees`
- Git doesn't recognize it
### Likely Cause
Incomplete removal or manual deletion
### Solutions
1. Check `git worktree list` to see git's view
2. If orphaned, remove directory manually: `rm -rf trees/branch-name`
3. If needed, prune git worktrees: `git worktree prune`
### What to tell the user
> It looks like there's an orphaned worktree. Let me clean it up...
---
## Issue 7: "Dependencies not installing"
### Symptoms
- Services fail to start
- Missing modules errors
- Build failures
### Solutions
1. Check the creation output for install errors
2. Manually run install in worktree: `cd trees/branch-name && npm install`
3. Verify package.json exists in worktree
---
## Issue 8: "Database issues in worktree"
### Symptoms
- Database errors
- Data conflicts between main and worktree
- Migrations not running
### Note
Each worktree should have isolated database configuration. Check:
1. .env file in worktree has unique DB settings
2. Database name includes branch identifier
3. Migrations ran successfully during creation
---
## General Debugging Approach
When user reports any issue:
1. **Gather information**
- Run `/list_worktrees` first
- Ask which specific worktree
- Ask what they were trying to do
2. **Diagnose**
- Check service status
- Verify port configuration
- Look for error patterns
3. **Resolve**
- Use appropriate command
- Verify fix worked
- Explain what happened
4. **Prevent**
- Suggest best practices
- Recommend cleanup of unused worktrees
- Note any configuration issues
---
## Quick Diagnostic Checklist
When troubleshooting, check:
- ✓ Does worktree directory exist? (`ls trees/`)
- ✓ Is git aware of it? (`git worktree list`)
- ✓ Are services running? (`/list_worktrees`)
- ✓ Are ports available? (check PIDs)
- ✓ Is configuration correct? (check .env, settings.json)
- ✓ Did dependencies install? (check node_modules)

267
commands/create_worktree_prompt.md Normal file
View File

@@ -0,0 +1,267 @@
---
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/<BRANCH_NAME>
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 <BRANCH_NAME>`
- 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/<BRANCH_NAME> <BRANCH_NAME>`
- 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/<BRANCH_NAME>
- Verify worktree was created: `git worktree list | grep trees/<BRANCH_NAME>`
- All subsequent operations will reference WORKTREE_DIR (which is PROJECT_CWD/trees/<BRANCH_NAME>)
### 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 <PROJECT_CWD>/.env <WORKTREE_DIR>/.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 <PROJECT_CWD>/.env.sample <WORKTREE_DIR>/.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=<calculated 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=<calculated CLIENT_PORT>
VITE_API_URL=http://localhost:<calculated SERVER_PORT>
VITE_WS_URL=ws://localhost:<calculated SERVER_PORT>/stream
VITE_MAX_EVENTS_TO_DISPLAY=100
OBSERVABILITY_SERVER_URL=http://localhost:<calculated SERVER_PORT>/events
```
- The OBSERVABILITY_SERVER_URL is critical for hooks to send events to correct server
### 7. Install Dependencies
- Install server dependencies:
- `cd <WORKTREE_DIR>/apps/server && bun install`
- Verify WORKTREE_DIR/apps/server/node_modules directory was created
- Install client dependencies:
- `cd <WORKTREE_DIR>/apps/client && bun install`
- Verify WORKTREE_DIR/apps/client/node_modules directory was created
- Return to worktree root: `cd <WORKTREE_DIR>`
### 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 <WORKTREE_DIR>`
- Start the system using the one-shot script in the BACKGROUND:
- Command: `cd <WORKTREE_DIR> && SERVER_PORT=<calculated SERVER_PORT> CLIENT_PORT=<calculated 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:<SERVER_PORT>/events/filter-options >/dev/null 2>&1`
- Check client: `curl -s http://localhost:<CLIENT_PORT> >/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:<CLIENT_PORT>`
- 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:<CLIENT_PORT>`
- 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_NAME>
Branch: <BRANCH_NAME>
Status: 🟢 RUNNING
🔌 Port Configuration:
Server Port: <SERVER_PORT>
Client Port: <CLIENT_PORT>
Port Offset: <PORT_OFFSET> (multiply by 10)
🌐 Access URLs (LIVE NOW):
🖥️ Dashboard: http://localhost:<CLIENT_PORT>
🔌 Server API: http://localhost:<SERVER_PORT>
📡 WebSocket: ws://localhost:<SERVER_PORT>/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 <SERVER_PORT> (background)
✓ Client started on port <CLIENT_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:<CLIENT_PORT> 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 :<SERVER_PORT> and lsof -i :<CLIENT_PORT>
🔄 To Restart This Worktree Later:
cd trees/<BRANCH_NAME>
# Kill existing processes first
lsof -ti :<SERVER_PORT> | xargs kill -9
lsof -ti :<CLIENT_PORT> | xargs kill -9
# Or use the one-shot script (it kills automatically)
SERVER_PORT=<SERVER_PORT> CLIENT_PORT=<CLIENT_PORT> sh scripts/start-system.sh > /dev/null 2>&1 &
🧹 To Stop This Worktree:
# Option 1: Manual kill
lsof -ti :<SERVER_PORT> | xargs kill -9
lsof -ti :<CLIENT_PORT> | xargs kill -9
# Option 2: Use reset script (with environment variables)
cd trees/<BRANCH_NAME>
SERVER_PORT=<SERVER_PORT> CLIENT_PORT=<CLIENT_PORT> ./scripts/reset-system.sh
🗑️ To Remove This Worktree:
# Stop services first (see above)
# Then remove the worktree:
git worktree remove trees/<BRANCH_NAME>
# Or force remove if needed:
git worktree remove trees/<BRANCH_NAME> --force
🎉 Next Steps:
1. Open http://localhost:<CLIENT_PORT> 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:
- <List any warnings or actions the user needs to take>
```

239
commands/list_worktrees_prompt.md Normal file
View File

@@ -0,0 +1,239 @@
---
model: claude-sonnet-4-5-20250929
description: List all git worktrees with their configuration and status
allowed-tools: Bash, Read, Glob, Grep
---
# Purpose
List all git worktrees in the `trees/` directory with comprehensive information including branch names, directories, environment variables, port configuration, and service status.
## Variables
```
PROJECT_CWD: . (current working directory - the main project root)
WORKTREE_BASE_DIR: trees/
```
## Instructions
- List all worktrees managed by git
- For each worktree in trees/, gather configuration details
- Read environment files to extract port configuration
- Check if services are running on configured ports
- Display comprehensive information in a clear, organized format
- Show which worktrees are active vs stopped
- Provide quick action commands for each worktree
## Workflow
### 1. List Git Worktrees
- Run: `git worktree list`
- Parse output to identify all worktrees
- Filter for worktrees in PROJECT_CWD/trees/ directory
- Extract:
- Worktree path
- Branch name
- Commit hash (if available)
### 2. Gather Configuration for Each Worktree
For each worktree found in trees/:
**Extract Branch/Directory Info:**
- Worktree directory: `trees/<branch-name>`
- Branch name from git worktree list
- Working directory path
**Read Server Configuration:**
- Check if `<worktree>/apps/server/.env` exists
- If exists, read and extract:
- `SERVER_PORT`
- `DB_PATH`
- If doesn't exist, note as "Not configured"
**Read Client Configuration:**
- Check if `<worktree>/apps/client/.env` exists
- If exists, read and extract:
- `VITE_PORT`
- `VITE_API_URL`
- `VITE_WS_URL`
- `VITE_MAX_EVENTS_TO_DISPLAY`
- If doesn't exist, note as "Not configured"
**Read Root Configuration:**
- Check if `<worktree>/.env` exists
- Note presence/absence (contains API keys, don't display values)
### 3. Check Service Status
For each worktree with port configuration:
**Check Server Status:**
- If SERVER_PORT identified, check: `lsof -i :<SERVER_PORT>`
- Determine if process is running
- Extract PID if running
**Check Client Status:**
- If VITE_PORT identified, check: `lsof -i :<VITE_PORT>`
- Determine if process is running
- Extract PID if running
### 4. Check Dependencies
For each worktree:
- Check if `<worktree>/apps/server/node_modules` exists
- Check if `<worktree>/apps/client/node_modules` exists
- Note if dependencies are installed or missing
### 5. Calculate Statistics
- Total number of worktrees
- Number with services running
- Number with services stopped
- Total ports in use
- Available port offsets (suggest next available)
### 6. Report
Follow the Report section format below.
## Report
After gathering all information, provide a comprehensive report in the following format:
```
📊 Git Worktrees Overview
═══════════════════════════════════════════════════════════════
📈 Summary:
Total Worktrees: <count>
Running: <count> | Stopped: <count>
Next Available Port Offset: <offset>
═══════════════════════════════════════════════════════════════
🌳 Main Repository (Default)
📁 Location: <project-root>
🌿 Branch: <current-branch>
🔌 Ports: 4000 (server), 5173 (client)
🎯 Status: <RUNNING|STOPPED>
Actions:
└─ Start: ./scripts/start-system.sh
└─ Stop: ./scripts/reset-system.sh
───────────────────────────────────────────────────────────────
🌳 Worktree: <branch-name>
📁 Location: trees/<branch-name>
🌿 Branch: <branch-name>
📝 Commit: <commit-hash-short>
⚙️ Configuration:
├─ Server Port: <SERVER_PORT>
├─ Client Port: <VITE_PORT>
├─ Database: <DB_PATH>
├─ API URL: <VITE_API_URL>
└─ WebSocket: <VITE_WS_URL>
📦 Dependencies:
├─ Server: <✓ Installed | ❌ Missing>
└─ Client: <✓ Installed | ❌ Missing>
🎯 Service Status:
├─ Server: <🟢 RUNNING (PID: xxxx) | 🔴 STOPPED>
└─ Client: <🟢 RUNNING (PID: xxxx) | 🔴 STOPPED>
🌐 Access URLs (if running):
├─ Dashboard: http://localhost:<VITE_PORT>
├─ Server API: http://localhost:<SERVER_PORT>
└─ WebSocket: ws://localhost:<SERVER_PORT>/stream
Actions:
├─ Start: cd trees/<branch-name> && SERVER_PORT=<port> CLIENT_PORT=<port> sh scripts/start-system.sh
├─ Stop: SERVER_PORT=<port> CLIENT_PORT=<port> ./scripts/reset-system.sh
└─ Remove: /remove_worktree <branch-name>
───────────────────────────────────────────────────────────────
[Repeat for each worktree]
═══════════════════════════════════════════════════════════════
💡 Quick Commands:
Create new worktree:
└─ /create_worktree <branch-name> [port-offset]
Remove worktree:
└─ /remove_worktree <branch-name>
Start a stopped worktree:
└─ cd trees/<branch-name> && SERVER_PORT=<port> CLIENT_PORT=<port> sh scripts/start-system.sh &
Stop a running worktree:
└─ lsof -ti :<SERVER_PORT> | xargs kill -9 && lsof -ti :<CLIENT_PORT> | xargs kill -9
View this list again:
└─ /list_worktrees
═══════════════════════════════════════════════════════════════
```
If no worktrees exist in trees/:
```
📊 Git Worktrees Overview
═══════════════════════════════════════════════════════════════
🌳 Main Repository (Default)
📁 Location: <project-root>
🌿 Branch: <current-branch>
🔌 Ports: 4000 (server), 5173 (client)
🎯 Status: <RUNNING|STOPPED>
═══════════════════════════════════════════════════════════════
ℹ️ No worktrees found in trees/ directory
💡 Create your first worktree:
/create_worktree <branch-name>
This will:
• Create isolated git worktree
• Configure unique ports (4010, 5183)
• Install dependencies
• Start services automatically
═══════════════════════════════════════════════════════════════
```
If worktrees have configuration issues:
```
⚠️ Configuration Warnings:
• trees/<branch-name>: Missing .env files
└─ Fix: Recreate with /create_worktree <branch-name>
• trees/<branch-name>: Dependencies not installed
└─ Fix: cd trees/<branch-name>/apps/server && bun install
└─ Fix: cd trees/<branch-name>/apps/client && bun install
• trees/<branch-name>: Services running but ports mismatch
└─ Fix: Stop services and update .env files
```
## Notes
- Main repository is always shown first (uses default ports)
- Worktrees are sorted alphabetically by branch name
- Service status is checked in real-time
- Port conflicts are detected and highlighted
- Orphaned worktrees (in git but not in trees/) are noted
- PIDs are shown for running processes for easy termination
- All commands are copy-paste ready

184
commands/remove_worktree_prompt.md Normal file
View File

@@ -0,0 +1,184 @@
---
model: claude-sonnet-4-5-20250929
description: Remove a git worktree, delete its branch, and stop its running services
argument-hint: <branch-name>
allowed-tools: Bash, Read, Glob, Grep
---
# Purpose
Remove an existing git worktree from the `trees/` directory AND delete the associated git branch. This includes stopping any running services on its ports, cleaning up processes, removing the worktree directory, and permanently deleting the branch. This ensures complete cleanup without orphaned processes or files.
## Variables
```
PROJECT_CWD: . (current working directory - the main project root)
BRANCH_NAME: $1 (required)
WORKTREE_DIR: trees/<BRANCH_NAME>
```
## Instructions
- This command safely removes a worktree and all associated resources
- Stops any running server and client processes for the worktree
- Removes the git worktree using git's built-in removal command
- Deletes the git branch associated with the worktree (PERMANENT)
- Validates that the worktree and branch were completely removed
- Provides clear feedback about what was removed and any issues encountered
- If services can't be stopped gracefully, force kills them
- Handles cases where worktree is already partially removed
- WARNING: Both worktree and branch deletion are permanent and cannot be undone
## Workflow
### 1. Parse and Validate Arguments
- Read BRANCH_NAME from $1, error if missing
- Construct WORKTREE_DIR path: `PROJECT_CWD/trees/<BRANCH_NAME>`
- Validate branch name format (no spaces, valid git branch name)
### 2. Check Worktree Existence
- List all worktrees: `git worktree list`
- Check if worktree exists at WORKTREE_DIR
- If worktree doesn't exist:
- Check if directory exists anyway (orphaned directory)
- If directory exists, note it for manual cleanup
- If neither exists, error with message that worktree not found
### 3. Identify Port Configuration
- Check if WORKTREE_DIR/apps/server/.env exists
- If exists, read SERVER_PORT from the file
- Check if WORKTREE_DIR/apps/client/.env exists
- If exists, read VITE_PORT from the file
- If env files don't exist, try to infer ports from worktree count:
- Count existing worktrees in PROJECT_CWD/trees/
- Estimate ports based on typical offset pattern
- Note: This is best-effort if env files are missing
### 4. Stop Running Services
- If SERVER_PORT identified, stop processes on that port:
- Find PIDs: `lsof -ti :<SERVER_PORT>`
- Kill processes: `kill -9 <PIDs>`
- Verify processes stopped
- If VITE_PORT identified, stop processes on that port:
- Find PIDs: `lsof -ti :<VITE_PORT>`
- Kill processes: `kill -9 <PIDs>`
- Verify processes stopped
- Check for any remaining processes in WORKTREE_DIR:
- `ps aux | grep "trees/<BRANCH_NAME>"`
- Kill any orphaned processes
- Wait 2 seconds for processes to fully terminate
### 5. Remove Git Worktree
- Remove worktree using git: `git worktree remove trees/<BRANCH_NAME>`
- If removal fails with error (e.g., worktree has uncommitted changes):
- Try force removal: `git worktree remove trees/<BRANCH_NAME> --force`
- Note the force removal in the report
- Verify worktree was removed: `git worktree list | grep trees/<BRANCH_NAME>`
- Should return nothing if successfully removed
### 6. Clean Up Orphaned Files
- Check if WORKTREE_DIR still exists after git worktree remove
- If directory still exists (shouldn't, but possible with force):
- Note this in warnings
- Do NOT automatically delete with rm -rf (security)
- Provide manual cleanup instructions
- Check for any SQLite WAL files in the removed worktree location
- Check for any lingering lock files
### 7. Delete Git Branch
- After worktree is successfully removed, delete the git branch:
- First try safe delete: `git branch -d <BRANCH_NAME>`
- If safe delete fails (unmerged changes), use force delete: `git branch -D <BRANCH_NAME>`
- Note in report if force delete was used
- Verify branch was deleted: `git branch --list <BRANCH_NAME>`
- Should return nothing if successfully deleted
- Important: This is destructive and permanent
### 8. Validation
- Confirm worktree no longer appears in: `git worktree list`
- Confirm directory no longer exists at WORKTREE_DIR
- Confirm branch no longer exists: `git branch --list <BRANCH_NAME>`
- Confirm no processes running on identified ports
- If any validation fails, include in warnings section
### 9. Report
Follow the Report section format below to provide comprehensive removal information.
## Report
After successful worktree removal, provide a detailed report in the following format:
```
✅ Git Worktree and Branch Removed Successfully!
📁 Worktree Details:
Location: trees/<BRANCH_NAME>
Branch: <BRANCH_NAME>
Status: ❌ REMOVED
🛑 Services Stopped:
✓ Server on port <SERVER_PORT> (if identified)
✓ Client on port <VITE_PORT> (if identified)
✓ All orphaned processes terminated
🗑️ Cleanup:
✓ Git worktree removed
✓ Git branch deleted
✓ Directory removed from trees/
✓ No lingering processes
📝 Important Notes:
• Both the worktree AND branch '<BRANCH_NAME>' have been deleted
• This removal is PERMANENT and cannot be undone
• If you need this branch again, create a new one with: /create_worktree <BRANCH_NAME>
• The new branch will start from your current HEAD
🔍 Verification:
✓ Worktree not in git worktree list
✓ Branch not in git branch list
✓ Directory trees/<BRANCH_NAME> removed
✓ Ports <SERVER_PORT>, <VITE_PORT> are free
```
If any issues occurred during removal, include a warnings section:
```
⚠️ Warnings / Issues:
- Used --force flag to remove worktree (had uncommitted changes)
- Used -D flag to force delete branch (had unmerged changes)
- Port <PORT> could not be identified (no .env file found)
- Processes manually killed: <PID1>, <PID2>
```
If worktree was already partially removed or not found:
```
⚠️ Worktree Status:
- Worktree 'trees/<BRANCH_NAME>' was not found in git worktree list
- Directory may have been manually deleted
- Run 'git worktree prune' to clean up worktree metadata
📝 Cleanup Command:
git worktree prune
```
If orphaned directory exists after removal:
```
⚠️ Manual Cleanup Required:
- Directory trees/<BRANCH_NAME> still exists after git worktree remove
- This should not happen normally
- To manually remove, run from PROJECT_CWD:
rm -rf trees/<BRANCH_NAME>
- Or use the reset script with port variables:
SERVER_PORT=<PORT> CLIENT_PORT=<PORT> ./scripts/reset-system.sh
```

73
plugin.lock.json Normal file
View File

@@ -0,0 +1,73 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:djacobsmeyer/claude-skills-engineering:plugins/manage-worktrees-skill",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "b0d3d5bbfe827461451f65aaf10387b10bb4fd64",
"treeHash": "2ab9447da43ba6c88a6746bef853134a001b0518cc0a233000812d501c507db5",
"generatedAt": "2025-11-28T10:16:27.479765Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "manage-worktrees-skill",
"description": "Comprehensive git worktree management for creating, listing, and removing worktrees. Use when the user wants to create new development environments, view worktree status, or manage the lifecycle of parallel development environments. Provides slash commands /create_worktree, /list_worktrees, and /remove_worktree.",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "EXAMPLES.md",
"sha256": "72554279a2fd182bc367fe30a3aca817e1cf30dd5667ee006fa1630efc484b1e"
},
{
"path": "REFERENCE.md",
"sha256": "c5caf646e3abc17cdaff63e5d80b0e132318bd5dfa8ebcda1b355685f93fc678"
},
{
"path": "OPERATIONS.md",
"sha256": "b0082ec1517e6c8e190292bc7830872cdafcfc2213fca17f2aacaa5e90fa9e8f"
},
{
"path": "TROUBLESHOOTING.md",
"sha256": "8531f319a99072bf159b658bf8ca45a3b7188ec6e6b4ccf20a18e2d1cb9db9cb"
},
{
"path": "README.md",
"sha256": "6526462686e02de943d3be1e662473f5a956529708ef6f6cadf18c4d1b5e9eaf"
},
{
"path": "SKILL.md",
"sha256": "bd78a24a90ab8b88ceeea9457227fe6d6f50a53a32e5b3c2e74ce0c5daca4637"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "94e58697cfe3c5bd71459770e7390e92fb101553cb9e8054e0cad28b307de974"
},
{
"path": "commands/list_worktrees_prompt.md",
"sha256": "1a902c246b120d3d6777d387d36268704c28f8ad890ac6ffa95ae72306c60358"
},
{
"path": "commands/create_worktree_prompt.md",
"sha256": "2860db2195dc29aa85870daf04850284b67fc1e9295e7f5a9fc59b814a0c4d28"
},
{
"path": "commands/remove_worktree_prompt.md",
"sha256": "f51457910944fdaa2dca41a02ccea4cb36d9b0022e7bb68270cf1ea65805a252"
}
],
"dirSha256": "2ab9447da43ba6c88a6746bef853134a001b0518cc0a233000812d501c507db5"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}