Port and process inspector for Windows, macOS and Linux (never kills)

What it does

Finds the cause of "address already in use" errors.

• Lists listening TCP ports and bound UDP ports with address, port, PID and process name
• --port 3000 shows only the process holding that port
• Uses netstat -ano and tasklist on Windows, lsof on macOS, and ss on Linux (falling back to lsof or netstat)
• Prints the command you could run to stop it (taskkill /PID ... or kill ...), with a warning for system processes
• Can parse saved command output from another machine
• JSON output

How to use

python scripts/ports.py --port 3000
python scripts/ports.py --proto tcp

Ask the agent "what is using port 3000?" and it explains what the process is and the safest fix (quit the app normally, use another port, and so on). Works with Claude, Codex, Hermes Agent and Cursor.

Requirements

• Python 3 (standard library only)
• Built-in OS tools (Windows: netstat and tasklist; macOS: lsof; Linux: one of ss, lsof or netstat)

Caveats

• It never stops a process; whether to stop one is your decision.
• Without admin or root rights, macOS and Linux may hide other users' processes.
• With WSL2 or Docker Desktop, a port-forwarding process may be shown as the owner.