susuyan/port-allocator

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