ports: project-aware lsof for macOS

lsof -iTCP -sTCP:LISTEN -nP | grep :3000 — everyone knows the command, nobody actually remembers it. And it only answers half the question: yes, something is on port 3000, but which of your five node processes?

ports fixes that. Single Go binary, zero dependencies, macOS only.

$ ports
PORT   PROTO  PID    COMMAND  PARENT  PATH                CAFFEINATE  AGE
3000   TCP    15711  node     zsh     ~/code/web-app      -           27m
3030   TCP    12405  node     zsh     ~/code/api          on:82031    2h
5432   TCP    23514  ssh      launchd ~/code/infra        -           10d

The project directory is right there in the output. No more cross-referencing PIDs with ps aux.

Kill, pause, inspect — no PID hunting

# Free up a port in one command
ports kill 3000

# Didn't shut down gracefully? Force it.
ports force-kill 3000

# Kill everything running under a project directory
ports kill --dir ~/code/web-app

# Freeze without killing (useful for debugging hanging requests)
ports pause 3000
ports resume 3000

# Full detail + HTTP probe
ports inspect 3000

--dir is the command I wish I’d had for years. One line to kill everything running under a project, without touching anything else.

What changes for an AI agent workflow

macOS will sleep your processes if the machine idles long enough. For agent sessions that run for hours, this is an actual problem. ports caffeinate attaches the native macOS caffeinate mechanism directly to the process you care about.

# Keep whatever owns this port awake
ports caffeinate 3000

# Keep an AI agent awake by name
ports caffeinate codex
ports caffeinate "claude code"

# Auto-caffeinate new child processes as they spawn
ports caffeinate codex --dir ~/code/agent --follow

# Find AI agent PIDs that don't listen on any port
ports --find codex "claude code" gemini cursor

--follow is the key feature for long sessions: as soon as a new child process appears under the project, it gets caffeinated automatically. Useful when Claude Code respawns its workers mid-session.

Install via Homebrew: brew install erdemylmaz/ports-cli/ports

Source: github.com/erdemylmaz/ports-cli