port-registry

Manages per-project port ranges to prevent server conflicts.

Updated Mar 21, 2026
One-click install
npx skills add https://github.com/Derek-X-Wang/skills --skill port-registry-derek-x-wang
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: port-registry
Source: https://github.com/Derek-X-Wang/skills/tree/main/port-registry
Command: npx skills add https://github.com/Derek-X-Wang/skills --skill port-registry-derek-x-wang

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When working on multiple projects locally, dev servers compete for the same default ports (3000, 3001, 8080, etc.). This skill manages a central registry at ~/.config/port-registry.json that assigns each project a dedicated port range.

Core Features & Use Cases

  • Central registry file at ~/.config/port-registry.json
  • Automatic allocation of per-project port ranges
  • Assignment mappings for typical services (web, backend, api)
  • Guidance for updating project configurations to use the assigned ports

Quick Start

Initialize or update port ranges for the current project and adjust your dev scripts accordingly.

Frequently Asked Questions about port-registry

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

FAQPage Schema
How do I prevent port conflicts when running multiple localhost dev servers?

Port conflicts occur when multiple local dev servers compete for the same default ports. A central registry solves this by assigning each project a dedicated port range, automatically allocating blocks to prevent EADDRINUSE errors across your local development environment.

Why does my dev server return an EADDRINUSE error across different projects?

An EADDRINUSE error happens when multiple projects attempt to use the same default dev server ports simultaneously. A central port registry resolves this by maintaining unique assignment mappings for each project's web, backend, and API services.

How do I assign a dedicated port range to a new project?

To assign a dedicated port range, initialize a central registry that supports automatic range allocation. When onboarding a new project, the system prompts for a project name and allocates a distinct block of ports for its local servers.

What's the best way to manage port configurations for multiple local servers?

The best way to manage port configurations is maintaining a central registry file storing block sizes, ranges, and assignment mappings. This provides automatic allocation and guidance for updating project configurations to use the assigned ports.

Do I need to manually configure port assignments for each project's services?

No, you do not need to manually configure port assignments. The port registry supports automatic range allocation and maintains assignment mappings for typical services like web, backend, and API, prompting for a project name only when necessary.