Portscope provides a command-line interface for viewing and managing processes bound to network ports on a local machine. Developers often face uncertainty when diagnosing port usage—such as identifying what occupies port 3000 during local server startups or handling collisions from orphaned processes. This JavaScript-based tool, available at Neilblaze/portscope with 35 GitHub stars, addresses that by offering real-time visibility into listening ports from development servers, databases, system daemons, and Docker containers. It includes heuristic detection for frameworks, process lifecycle controls, and AI-driven natural language queries, all within an interactive interface.

The tool runs on Node.js version 18 or higher and follows the Apache 2.0 license. Its npm package shows the latest version via badges on the repository. A companion site at neilblaze.github.io/portscope/ hosts additional details.

Core features

Portscope displays a table of active ports upon launch, highlighting processes, memory usage, and container associations where applicable. Key capabilities include:

  • Interactive prompt: After showing the port table, it enters a REPL-like mode that remains active until exit or Ctrl+C. Users type port numbers (e.g., 3000) for inspection, commands like kill 3000, ps, or clean, or natural language questions such as "what's using the most memory?" The AI component processes these queries and suggests or performs actions.
  • Framework and container detection: It identifies common development frameworks and maps Docker containers automatically, providing context like service names or PIDs.
  • Slash commands and tab completion: Options like /provider, /models, and /help configure AI settings; typing / followed by Tab reveals completions.
  • Non-interactive modes: Flags such as --all list all listening ports, including system services and desktop apps. Specific ports get detailed views via portscope 3000 or the whoisonport 3000 alias.
  • Persistent session: Unlike one-shot commands, it supports ongoing management, reducing the need to relaunch for repeated checks.

A demo video on the README shows the table updating live, with the prompt accepting inputs fluidly. This setup aggregates metrics into what the README calls a "high-fidelity control plane" for local debugging.

Getting it running

Installation requires Node.js >=18. Use npm for global access:

npm install -g portscope

For one-off runs without installation:

npx portscope

The README suggests compatibility with tools like Claude Code or Gemini CLI for direct execution in those environments. No additional dependencies appear in the docs; it pulls from standard system calls and npm ecosystem.

Launch interactive mode with:

portscope

This prints the port table—typically showing user-space listeners like Node servers or Python apps—and drops into the prompt. For broader visibility:

portscope --all

Inspect a port:

portscope 3000

or

whoisonport 3000

Cross-platform support covers macOS, Linux, and Windows, as it leverages Node's portability and native OS port-scanning methods. The tool handles elevated privileges implicitly for system ports when needed, though users may require sudo on restricted systems for full --all scans.

Who this is for

Local developers benefit most, especially those juggling multiple services. Frontend engineers starting Next.js on 3000 might clash with lingering React dev servers; backend teams debugging Express or FastAPI apps gain quick PID and memory insights. Docker users appreciate the container mapping, which links ports to specific images without manual docker ps checks.

In practice, it suits workflows with frequent port troubleshooting: spinning up databases like PostgreSQL (5432), Redis (6379), or ad-hoc tools. The AI layer helps non-experts phrase queries conversationally, such as "kill the highest memory process on port 8080," while experts stick to commands like ps for process trees. Teams on laptops with mixed workloads—IDEs, browsers, and CLIs—find the interactive mode cuts context-switching time.

It's less ideal for servers or production monitoring, where tools like Prometheus offer persistent metrics. Remote or cloud-based port scans fall outside its local focus.

How it compares

Standard Unix tools like lsof -i :3000, netstat -tulpn, or ss -tulpn provide raw port data but lack interactivity or AI. On macOS, lsof -i TCP:3000 works similarly, while Windows users rely on netstat -ano | findstr :3000. These require piping to grep or kill for management, without tables or natural language.

Dedicated alternatives include nethogs for bandwidth per process or fuser -k 3000/tcp for kills, but none combine listing, inspection, and REPL in one package. GUI options like lsof wrappers in VS Code extensions exist, yet Portscope stays terminal-native. For Docker-specific views, docker port lists mappings, but misses host processes.

Portscope stands heavier than lsof due to Node.js and AI (Ollama or API providers configurable via /provider), with startup overhead around 100-500ms on typical machines. It trades that for richer context, like framework labels (e.g., "Next.js").

Portscope fits developers tired of fragmented port commands, available via GitHub or npm.

View on GitHub →Official Website →