port-manager

Manage cross-project localhost port allocation. Prevents port conflicts when multiple Claude Code instances work on different projects simultaneously.

Architecture

~/.claude/
├── port-registry.json              # Central registry (source of truth)
├── hooks/
│   └── check-port.sh               # PreToolUse hook (auto-installed)
└── skills/
    └── port-manager/
        ├── SKILL.md                 # This file
        ├── port-manager.md          # Command definition
        ├── scripts/
        │   ├── setup.sh             # One-click installer
        │   ├── check-port.sh        # Hook script source
        │   └── port-helpers.sh      # Shell helper functions
        └── examples/
            └── port-registry.example.json  # Registry template

Port Registry Format

{
  "version": "1.0.0",
  "updated_at": "2026-02-08",
  "port_ranges": {
    "reserved": { "min": 1024, "max": 8999, "description": "Project ports" },
    "available": { "min": 9000, "max": 9999, "description": "Allocation pool" },
    "system": { "min": 1, "max": 1023, "description": "System reserved" }
  },
  "ports": {
    "3000": {
      "project": "my-app",
      "service": "Backend API (Koa)",
      "added": "2026-02-08"
    }
  }
}

Detection Mechanism

The PreToolUse hook (check-port.sh) uses two layers of detection:

Layer 1: Explicit Port Detection

Regex patterns matched against Bash command strings:

Layer 2: Indirect Startup Detection

When npm run dev, pnpm dev, bun run dev, etc. are detected:

1. package.json scripts — extract --port from script commands
2. vite.config.{ts,js,mts,mjs} — extract port: value
3. next.config.{js,mjs,ts} — extract port: value
4. .env / .env.local / .env.development — extract PORT=, VITE_PORT=, DEV_PORT=
5. Registry fallback — if no port found in config files, look up all ports registered to the current project and check if they're occupied

Project Resolution

The hook resolves the current project name by walking up from $PWD to find the nearest .git directory or CLAUDE.md file. This correctly handles monorepo subdirectories (e.g., my-app/packages/client/ resolves to my-app).

Conflict Actions

Shell Helper Functions

Installed to ~/.claude/skills/port-manager/scripts/port-helpers.sh, sourced via ~/.zshrc:

Setup Components

The /port-manager setup command installs:

1. Port registry — ~/.claude/port-registry.json (from template)
2. Hook script — ~/.claude/hooks/check-port.sh
3. PreToolUse hook config — added to ~/.claude/settings.json
4. SessionStart integration — port summary in ~/.claude/hooks/session-start.sh
5. Shell functions — source reference in ~/.zshrc
6. CLAUDE.md section — port management rules appended

Uninstall

# Remove registry
rm ~/.claude/port-registry.json

# Remove hook
rm ~/.claude/hooks/check-port.sh

# Manual cleanup needed:
# - ~/.claude/settings.json: remove PreToolUse hook entry for check-port
# - ~/.claude/hooks/session-start.sh: remove port summary section
# - ~/.zshrc: remove port-helpers.sh source line
# - ~/.claude/CLAUDE.md: remove port management section

Known Limitations