portmap

Stop guessing what's running on your ports.

---

A fast, cross-platform CLI tool that shows what dev processes are running on your machine's network ports — with framework detection, Docker container identification, health monitoring, and JSON output.

$ portmap
┌──────┬───────┬─────────┬───────────┬────────────┬────────┬────────┐
│ PORT │  PID  │ PROCESS │ FRAMEWORK │   STATUS   │ MEMORY │ UPTIME │
├──────┼───────┼─────────┼───────────┼────────────┼────────┼────────┤
│ 3000 │ 12345 │ node    │ Next.js   │ ● healthy  │ 120MB  │ 2h 15m │
│ 5173 │ 23456 │ node    │ Vite      │ ● healthy  │ 85MB   │ 45m    │
│ 5432 │ 45678 │ docker  │ PostgreSQL│ ● healthy  │ 250MB  │ 3d 2h  │
│ 8000 │ 56789 │ Python  │ FastAPI   │ ○ orphaned │ 40MB   │ 5d 12h │
│ 8080 │ 34567 │ python  │ Django    │ ● healthy  │ 60MB   │ 1h 30m │
└──────┴───────┴─────────┴───────────┴────────────┴────────┴────────┘

Features

• Framework Detection — Identifies 50+ frameworks from command lines and project files
• Cross-Platform — Works on macOS, Linux, and Windows
• Docker Aware — Detects containers and maps images to services (PostgreSQL, Redis, etc.)
• Health Monitoring — Flags orphaned and zombie processes
• Watch Mode — Live-updating TUI that refreshes every 2 seconds
• JSON Output — Pipe-friendly output for scripting and automation
• Kill & Clean — Interactively kill processes or clean up orphans
• Zero Config — Just install and run. No setup needed.

Install

Homebrew (macOS / Linux):

brew install AimenHallou/tap/portmap

Go:

go install github.com/AimenHallou/portmap@latest

Binary download: Grab the latest release from Releases for your platform.

Usage

portmap                     # show dev ports (default)
portmap --all               # include system processes
portmap 3000                # detailed view for a specific port
portmap ps                  # full process table
portmap watch               # live-updating monitor (press q to quit)
portmap kill 3000           # kill process on port 3000
portmap kill 3000 --force   # kill without confirmation
portmap clean               # find and kill orphaned/zombie processes
portmap clean --force       # kill all orphans without confirmation
portmap --json              # JSON output (works with any command)
portmap version             # print version info

JSON Output

Use --json with any command for structured output:

portmap --json | jq '.[] | select(.framework == "Next.js")'

{
  "port": 3000,
  "pid": 12345,
  "process": "node",
  "framework": "Next.js",
  "status": "healthy",
  "memory_bytes": 125829120,
  "memory": "120.0MB",
  "uptime": "2h 15m",
  "command": "node /usr/local/bin/next dev",
  "directory": "/Users/you/projects/my-app",
  "docker": null
}

Watch Mode

Real-time port monitoring with a terminal UI:

portmap watch          # dev processes only
portmap watch --all    # everything

Press q to quit.

Detected Frameworks

portmap identifies 50+ frameworks and tools across every major ecosystem:

Ecosystem	Frameworks
JavaScript	Next.js, Vite, Nuxt, SvelteKit, Remix, Astro, Angular, React, Vue, Express, Fastify, NestJS, Hono, Koa, Gatsby
Python	Django, Flask, FastAPI, Streamlit, Jupyter
Ruby	Rails, Sinatra
JVM	Spring Boot, Ktor
C# / .NET	ASP.NET, Blazor
Go	Gin, Echo, Fiber, Chi
Rust	Actix, Axum, Rocket
PHP	Laravel, Symfony, WordPress
Elixir	Phoenix
Dev Tools	Storybook, Prisma Studio, Docker Compose, Firebase, Supabase, K8s port-forwards, Grafana, Prometheus
Docker	PostgreSQL, Redis, MySQL, MongoDB, nginx, RabbitMQ, Kafka, Elasticsearch, MinIO, LocalStack

Detection works in two passes:

1. Command line — pattern matching against the running process command
2. Project files — inspects package.json, go.mod, Cargo.toml, Gemfile, composer.json, pom.xml, .csproj, mix.exs, and config files in the working directory

How It Works

portmap uses gopsutil for cross-platform process and network data, with thin platform-specific fallbacks for working directory resolution:

• macOS — lsof for cwd resolution
• Linux — /proc/<pid>/cwd symlinks
• Windows — best-effort from command line paths

By default, portmap filters out system and desktop apps (Spotify, Chrome, Slack, etc.) and shows only dev-relevant processes. Use --all to see everything.

Building from Source

git clone https://github.com/AimenHallou/portmap.git
cd portmap
go build -o portmap .
./portmap

Run tests:

go test ./...                          # unit tests
go test -tags=integration -v .         # integration tests

License

MIT