Skip to content

Wirasm/worktree-manager-skill / .claude/skills

worktree-manager

Verified

Create, manage, and cleanup git worktrees with Claude Code agents across all projects. USE THIS SKILL when user says "create worktree", "spin up worktrees", "new worktree for X", "worktree status", "cleanup worktrees", "sync worktrees", or wants parallel development branches. Also use when creating PRs from a worktree branch (to update registry with PR number). Handles worktree creation, dependency installation, validation, agent launching in Ghostty, and global registry management.

FileKindSize
SKILL.mdskill md21.9 KB
config.jsonconfig361 B
scripts/allocate-ports.shexecutablescript2.5 KB
scripts/cleanup.shexecutablescript6.5 KB
scripts/launch-agent.shexecutablescript4.7 KB
scripts/register.shexecutablescript3.6 KB
scripts/release-ports.shexecutablescript1.0 KB
scripts/status.shexecutablescript6.2 KB
scripts/sync.shexecutablescript5.0 KB
templates/worktree.jsonconfig581 B

scripts/allocate-ports.sh

View on GitHub
#!/bin/bash
# allocate-ports.sh - Allocate N unused ports from global pool
#
# Usage: ./allocate-ports.sh <count>
#
# Returns: Space-separated list of port numbers
# Example: ./allocate-ports.sh 2 → "8100 8101"
#
# Also updates the registry to mark ports as allocated

set -e

COUNT="${1:-2}"

# Validate input
if ! [[ "$COUNT" =~ ^[0-9]+$ ]] || [ "$COUNT" -lt 1 ]; then
    echo "Error: Count must be a positive integer" >&2
    exit 1
fi

# Find config and registry
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
CONFIG_FILE="$SCRIPT_DIR/../config.json"
REGISTRY="${HOME}/.claude/worktree-registry.json"

# Load port pool from config
if [ -f "$CONFIG_FILE" ] && command -v jq &> /dev/null; then
    PORT_START=$(jq -r '.portPool.start // 8100' "$CONFIG_FILE")
    PORT_END=$(jq -r '.portPool.end // 8199' "$CONFIG_FILE")
else
    PORT_START=8100
    PORT_END=8199
fi

# Check jq is available
if ! command -v jq &> /dev/null; then
    echo "Error: jq is required. Install with: brew install jq" >&2
    exit 1
fi

# Initialize registry if it doesn't exist
if [ ! -f "$REGISTRY" ]; then
    mkdir -p "$(dirname "$REGISTRY")"
    cat > "$REGISTRY" << EOF
{
  "worktrees": [],
  "portPool": {
    "start": $PORT_START,
    "end": $PORT_END,
    "allocated": []
  }
}
EOF
fi

# Get currently allocated ports from registry
ALLOCATED_PORTS=$(jq -r '.portPool.allocated // [] | .[]' "$REGISTRY" 2>/dev/null || echo "")

# Function to check if port is in use (by system or in registry)
is_port_available() {
    local port=$1

    # Check if in registry's allocated list
    if echo "$ALLOCATED_PORTS" | grep -q "^${port}$"; then
        return 1
    fi

    # Check if port is actually in use by system
    if lsof -i :"$port" &>/dev/null; then
        return 1
    fi

    return 0
}

# Find available ports
FOUND_PORTS=()
for ((port=PORT_START; port<=PORT_END; port++)); do
    if is_port_available "$port"; then
        FOUND_PORTS+=("$port")
        if [ ${#FOUND_PORTS[@]} -eq "$COUNT" ]; then
            break
        fi
    fi
done

# Check if we found enough ports
if [ ${#FOUND_PORTS[@]} -lt "$COUNT" ]; then
    echo "Error: Could not find $COUNT available ports in range $PORT_START-$PORT_END" >&2
    echo "Found only: ${FOUND_PORTS[*]}" >&2
    exit 1
fi

# Update registry with newly allocated ports
TMP=$(mktemp)
PORTS_JSON=$(printf '%s\n' "${FOUND_PORTS[@]}" | jq -R 'tonumber' | jq -s .)
jq ".portPool.allocated = ((.portPool.allocated // []) + $PORTS_JSON | unique | sort_by(.))" "$REGISTRY" > "$TMP" && mv "$TMP" "$REGISTRY"

# Output the ports (space-separated)
echo "${FOUND_PORTS[*]}"
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall