port-allocator

name	port-allocator
description	Automatically allocate and manage development server ports, avoiding port conflicts between multiple Claude Code instances

Port Allocator

Smart port allocator that only assigns ports to real projects containing package.json.

Usage

Command	Description
/port-allocator	Allocate/query port for current project
/port-allocator list	List all allocated ports
/port-allocator scan	Scan code directory, discover and allocate ports for new projects
/port-allocator config <path>	Set the main code directory path
/port-allocator add <dir-path>	Manually add port allocation for a project
/port-allocator allow	Configure Claude Code permissions for this skill's commands

Important Rules

1. Only Operate on Current Project's Ports When Restarting Services

When restarting the development server, only kill processes within the current project's port range, never affect other ports:

# Correct: Only kill current project ports (e.g., 3000-3009)
lsof -ti:3000 | xargs kill -9 2>/dev/null
lsof -ti:3001 | xargs kill -9 2>/dev/null

# Wrong: Kill all node processes or other ports
pkill -f node  # Will affect other projects!
lsof -ti:3010 | xargs kill  # This is another project's port!

2. Append Rather Than Overwrite When Updating CLAUDE.md

When updating ~/.claude/CLAUDE.md, must preserve the user's existing content:

# Correct: Check and append or update specific sections
# Wrong: Directly overwrite the entire file

Execution Steps

Command: /port-allocator allow

Configure Claude Code to allow commands used by this skill, avoiding manual confirmation each time:

1. Read ~/.claude/settings.json (if exists)
2. Merge the following commands into permissions.allow array (preserve existing config):

{
  "permissions": {
    "allow": [
      "Bash(ls -d *)",
      "Bash(find * -maxdepth * -name package.json *)",
      "Bash(cat ~/.claude/*)",
      "Bash(dirname *)",
      "Bash(lsof -i:3*)",
      "Bash(lsof -ti:3*)"
    ]
  }
}

3. Write updated settings.json
4. Output the list of added permissions

Output Format:

Configured Claude Code permissions

Added allowed command patterns:
  - Bash(ls -d *)
  - Bash(find * -maxdepth * -name package.json *)
  - Bash(cat ~/.claude/*)
  - Bash(lsof -i:3*)
  - Bash(lsof -ti:3*)

Config file: ~/.claude/settings.json

Command: /port-allocator config <path>

Set the user's main code directory:

1. Verify path exists (required! Error and exit if not found)
2. Update code_root field in ~/.claude/port-registry.json
3. Output confirmation

First Run: Auto-Detection

On first run (when ~/.claude/port-registry.json doesn't exist or has no code_root), automatically detect the code directory:

# Check common code directories
for dir in ~/Codes ~/Code ~/Projects ~/Dev ~/Development ~/repos; do
  if [ -d "$dir" ]; then
    CODE_ROOT="$dir"
    break
  fi
done

# If none exist, default to ~/Codes
CODE_ROOT="${CODE_ROOT:-~/Codes}"

Auto-detection output:

First run, detecting code directory...

Code directory detected: ~/Codes

Port registry initialized: ~/.claude/port-registry.json

To change, use:
   /port-allocator config ~/your/code/path

If no directory found:

Could not auto-detect code directory.

Please configure manually:
   /port-allocator config ~/your/code/path

Common locations:
   ~/Codes, ~/Code, ~/Projects, ~/Dev

Command: /port-allocator scan

Scan code directory, automatically discover and register projects:

1. Read ~/.claude/port-registry.json to get code_root
   • If config doesn't exist, run auto-detection first
   • If code_root directory doesn't exist, prompt user to configure
2. Find all directories containing package.json (exact to package.json location):

# Find all package.json, exclude build artifact directories
find <code_root> -maxdepth 3 -name "package.json" -type f \
  -not -path "*/.next/*" \
  -not -path "*/node_modules/*" \
  -not -path "*/dist/*" \
  -not -path "*/build/*" | while read pkg; do
  dirname "$pkg"
done

3. Important: Path must be exact to the directory containing package.json

   • Correct: ~/Codes/chekusu/landing
   • Wrong: ~/Codes/chekusu (if package.json is in subdirectory)

4. For each discovered project directory:

   • Check if already in registry
   • If not, allocate next available port range

5. Update config file (append mode, don't overwrite user content)

6. Output scan result summary

Command: /port-allocator (default)

Allocate/query port for current project:

1. Get current working directory
2. Read config to get code_root and allocated ports
3. Match current directory to corresponding project
4. If no package.json, indicate this is not a project needing ports
5. If exists, check if port already allocated, auto-allocate if not
6. Output port info

Command: /port-allocator list

List all allocated ports (read-only operation).

Output Format

Port Information

Project directory: ~/Codes/chekusu/landing
package.json: Detected
Port range: 3000-3009
   - Main app: 3000
   - API: 3001
   - Other services: 3002-3009

Warning: Only operate on ports 3000-3009 when restarting services!

Scan Results

Scan complete: ~/Codes

Registered projects (N):
   - chekusu/landing: 3000-3009
   - saifuri: 3010-3019

Newly discovered projects (M):
   - new-project: 3090-3099 (newly allocated)

Skipped (K):
   - .next, node_modules (build artifacts)
   - research-folder (no package.json)

Port Allocation Rules

• Each project is allocated 10 consecutive ports
• Starting port: 3000
• Interval: 10
• x0: Main application (e.g., 3000, 3010, 3020)
• x1: API service (e.g., 3001, 3011, 3021)
• x2-x9: Other services (database, cache, etc.)

Configuration Files

• Port registry: ~/.claude/port-registry.json
• Global instructions: ~/.claude/CLAUDE.md (append mode updates)
• Claude Code settings: ~/.claude/settings.json (stores allowedCommands)
• Skip patterns: .next, node_modules, dist, build

Notes

1. Only operate on project ports - Never affect other projects when restarting services
2. Append not overwrite - Preserve user's existing content when updating config files
3. Precise paths - Point to actual directory containing package.json
4. Skip build artifacts - .next, node_modules, etc. don't get port allocation
5. First use - Recommend running /port-allocator allow to configure permissions first