CLI · version 1.0
Port Pilot
Control every local service from a native macOS menu bar companion, live terminal dashboard, or agent-friendly CLI — with shared health context and safe process actions.
The full source, tests, and documentation live in the public repository. MIT licensed. Issues and pull requests are off: fork it and make it yours.
Why I built this
A busy local port usually begins a scavenger hunt through lsof, ps, browser tabs, and kill commands. Port Pilot turns that repeated debugging ritual into one readable view with enough context to act confidently.
The native menu bar companion is for everyday work; the terminal dashboard is for keyboard-driven sessions; and structured JSON, exit codes, waits, aliases, and lifecycle events give coding agents and scripts the same reliable understanding of the machine.
Your local services, under control
See the port. Understand the process. Act safely.
- Control services from the macOS menu bar.
- Inspect every listener and verify its health.
- Wait and watch from scripts or agents.
- Stop the right process tree deliberately.
Features
Compact menu companion
See cached ports immediately while startup refreshes in the background, search or show all listeners, open in-panel details, and safely stop local services without Dock clutter.
Live terminal dashboard
See listeners, projects, frameworks, owners, PIDs, CPU, memory, uptime, commands, and process ancestry in one keyboard-driven terminal interface.
HTTP health context
Recognize likely web services and show protocol, response status, page title, final URL, and response time with bounded local probes.
Safe process trees
Preview the exact target, confirm explicitly, signal descendants before the listener, and escalate from graceful termination only when necessary.
Agent-ready JSON
Use structured list, check, wait, watch, alias, and stop results without scraping colored terminal tables.
Automation primitives
Check availability through exit codes, wait for ready/free/HTTP conditions, and stream start, stop, or change events.
Docker awareness
Map published ports to container name, image, and private port automatically when Docker is available.
Development-first views
Start with services backed by project, framework, runtime, or Docker evidence, then opt into system and unknown listeners with a CLI flag, terminal filter, or native toggle.
Aliases and actions
Name important ports, open services and editors, and copy URLs, ports, commands, or directories from the dashboard.
Native notifications
See service start, stop, and HTTP health changes through macOS notifications; optionally launch the companion at login.
Use cases
Daily development
Understand every local listener before starting another web app, database, worker, or proxy.
Menu bar workflow
Keep service health, details, common actions, and aliases within one compact click on macOS.
AI coding agents
Let agents inspect JSON state, test port availability, wait for readiness, and stop only explicitly authorized disposable processes.
Startup orchestration
Wait until APIs return the expected HTTP status before starting dependent services or browser tests.
Container debugging
Connect host ports to Docker containers without switching to a separate process or container dashboard.
Team tooling
Distribute one consistent, documented port-inspection and safety workflow across a development team.
Product foundation
Reuse the scanner adapters, typed records, SwiftUI companion, Ink dashboard, Commander tree, and two test suites for another developer utility.
Tech stack
Runtime
Node.js
Runs the CLI, probes local HTTP endpoints, and talks to operating-system tools without a hosted backend.
Domain model
TypeScript
Keeps port, process, health, Docker, filters, aliases, and command results explicit.
Terminal interface
React and Ink
Render the live dashboard, selection state, confirmation, detail context, and keyboard actions.
Automation CLI
Commander
Defines discoverable commands and flags for people, shell scripts, CI, and coding agents.
System adapters
Execa
Invokes lsof, ss, ps, Docker, and clipboard providers with bounded, structured execution.
Native companion
SwiftUI and AppKit
Create a data-rich menu bar window with notifications, workspace actions, user defaults, and launch at login.
CLI
The same scanner and safety model are available as structured commands for terminal workflows, scripts, CI, and coding agents.
portsOpen the interactive development-service dashboard.
ports list --jsonReturn detected development services as structured JSON.
ports list --allInclude system and unknown listeners explicitly.
ports check 4321 --jsonInspect one port with process and HTTP context.
ports wait 4321 --http 200Wait until a local web service is healthy.
ports kill 4321Preview and confirm safe process-tree termination.
Screenshots and demos
What’s included
- Complete sanitized TypeScript source and reproducible package lock
- Complete SwiftUI menu bar companion source, Swift package, native tests, and reproducible app-bundle script
- Interactive dashboard plus scriptable inspection and process commands
- macOS and Linux scanners with optional Docker and HTTP enrichment
- JSON output, exit codes, waits, watch events, aliases, filters, and completions
- Automated tests, type checking, production build, and smoke-test guidance
- A README with the build story, architecture, decisions, customization, deployment, configuration, and security guides, plus AGENTS.md for coding agents
Documentation
The documentation lives in the repository, in one README: setup and usage, why I built it, how it was built, architecture, configuration, deployment, customization, security, the technical decisions, and the changelog. AGENTS.md gives coding agents the project context and operating rules.
Why use this
- Start from a substantial terminal product instead of another single-purpose kill-port script
- Reuse a typed, best-effort process-enrichment pipeline that stays useful when optional context is unavailable
- Give coding agents machine-readable state and safe, explicit process authority
- Study one domain model shared cleanly between a native SwiftUI client, Ink TUI, and Commander CLI
- Own and distribute a customized version with no hosted infrastructure or recurring cost
- Extend tested operating-system boundaries rather than spreading shell parsing across commands
Customize it
Use the working source as a foundation. Keep it small, change it for your own workflow, or turn it into a different product.
- Turn it into the port desk your team opens every morning: shared aliases, project groups, and a signed macOS companion.
- Publish through npm or Homebrew and make “what is on :3000?” a one-command habit for every machine.
- Add Windows, Podman, or remote-host scanners so the same mental model works beyond a single laptop.
- Wire JSON watch/wait output into editor tasks, CI gates, or MCP tools that wait until a service is ready.
- Detect frameworks, readiness rules, and custom columns so the table explains your stack instead of raw PIDs.
- Pair it with Local Hoster and sell (or gift) a complete local-dev toolkit under your own brand.
MIT license
The repository includes an MIT LICENSE file. You can use, copy, change, publish, distribute, sublicense, or sell the code, including as part of a commercial product.
Keep the copyright and license notice with copies or substantial portions of the code. Third-party dependencies and assets keep their own licenses.
Keep learning
Ship Factory
Build repeatable software workflows where people and coding agents can inspect the same system state.