port-allocator

Allocate and manage per-project development server port ranges for Claude Code instances.

Updated Jan 20, 2026
One-click install
npx skills add https://github.com/susuyan/skills --skill port-allocator
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: port-allocator
Source: https://github.com/susuyan/skills/tree/main/port-allocator
Command: npx skills add https://github.com/susuyan/skills --skill port-allocator

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill eliminates the manual overhead of managing port conflicts across multiple Claude Code instances by automatically allocating, tracking, and refreshing per-project port ranges.

Core Features & Use Cases

  • Per-project port allocation: assigns a dedicated 10-port range to each project containing a package.json.
  • Auto-detection & scanning: automatically detects code roots and discovers new projects via package.json.
  • Safe operations: avoids touching non-project processes and build artifacts, and persists state to a registry.

Quick Start

Use the /port-allocator commands to configure your code root, scan for projects, and query or assign ports for the current project.

Frequently Asked Questions about port-allocator

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent development server port conflicts across multiple Claude Code instances?

To prevent development server port conflicts, this skill automatically allocates and manages per-project port ranges. It assigns a dedicated 10-port range to each project containing a package.json and tracks them in a central registry.

How do I automatically allocate and track dev server ports for Node.js projects?

You can automatically allocate dev server ports by scanning your configured code root for package.json files. The skill auto-detects projects, assigns deterministic port ranges, and updates the port registry.

Does the port allocator work with projects that don't have a package.json?

No, the port allocator requires a package.json file to identify and manage projects. It operates exclusively on projects containing this file within your configured code root to assign and track port ranges.

How does automated port allocation handle build artifacts and non-project processes?

Automated port allocation safely excludes build artifacts and avoids touching non-project processes. It enforces deterministic port ranges per project and persists the state to a registry to ensure safe operations.

What is the best way to configure a code root for automatic port allocation in Claude Code?

The best way to configure your code root for automatic port allocation is using the /port-allocator commands. You can set the code root, scan for new projects, and query or assign ports for the current project directly.

Why does my development port registry need to be refreshed?

Your development port registry needs refreshing to discover new projects via package.json and prevent conflicts across multiple Claude Code instances. The skill updates the registry and CLAUDE.md as needed to maintain accurate port tracking.