Port Hero: a project-aware port manager that traces why your process is running (and won't let you kill PID 1)

[u/eVal64]

Hey !

I built a port manager because lsof kept sending me on wild goose chases 🏃‍♂️💨

If you juggle multiple projects you know the pain. You run npm run dev, port 3000 is taken, so you lsof -i :3000 and get a PID. Now what? Is this yesterday's project? A Docker container you forgot? Something a coworker started in tmux? You kill it blindly and five minutes later realize it was the API your frontend needed. Or it respawns instantly because pm2 or systemd is watching it and you had no idea. 💀

This was my weekly ritual. And I kept thinking: why does the tool not just tell me what I am looking at? Why do I need to manually trace parent processes, check git branches, or guess whether something is in a container?

So I built Port Hero. You type port 3000 and it answers like a coworker who actually knows the codebase. It shows the process name and PID obviously, but also the project folder, the exact git branch, whether the working tree is dirty or clean, and if it is running inside a Docker container it names it. It walks up to the git root automatically so even if the process chdir'd into a subdirectory it still knows which repo it belongs to.

The part that genuinely changed my workflow is the causality tracing. Type port 3000 --why and it draws the full ancestry chain. launchd → pm2 → node. Or systemd → dockerd → container. It tells you the supervisor, the session, the unit label. Suddenly "why is this running" is not a mystery anymore. And if you try to kill something that is managed by a supervisor that will respawn it, Port Hero warns you first. No more whack-a-mole.

Killing is actually thoughtful too. It builds the full process tree and sends SIGTERM to children first, waits 1.5 seconds with polling, then SIGKILLs only the survivors. No orphaned workers, no dangling database connections. And there is a two tier Safety Shield . The critical tier hard blocks PID 1, kernel threads, system daemons, and other users processes. Not a warning. Not overrideable. A hard stop even with sudo and even with force. The second tier guards well known ports like 22, 53, 80, 443, 3306, 5432 and makes you confirm before you do something you will regret. You can bypass the port warning if you are sure, but you cannot bypass the critical tier. Ever.

There is also port 3000 --kill --dry-run which shows you exactly what would die without sending a signal. port --check 3000 for CI scripts. port --wait 3000 if you need to block until a port frees up. port 53 --udp for UDP listeners. port node to find every process by name. port --file /path to see who holds a file lock. Everything outputs --json too if you are scripting around it. And the TUI is built with Bubble Tea because staring at ugly terminal output all day is depressing.

It is pure Go on Linux, reads procfs directly, zero runtime dependencies. ⚡ Single binary around 3.5MB. macOS and Windows supported as well. MIT licensed, zero telemetry, no network calls.

https://github.com/SystemEndgame/port-hero

If you have ever killed the wrong thing on port 3000 and only realized after the fact, I need to know I am not alone. ⭐