DEV Community

hao li
hao li

Posted on

I stopped letting my agents guess ports

#ai #devtools #python #claudecode

Run three Claude Code sessions at once and you know this feeling: the API server was on 3000, now it's on 3001, now something else grabbed 3001 and Vite jumped to 5174. Then an agent curls the wrong port, gets ECONNREFUSED, and confidently starts "fixing" code that was never broken.

I kept watching this failure mode in the r/ClaudeCode thread asking how people keep multiple sessions organized (89 points, 157 comments at the time of writing). Lots of session-panel tools. Almost nobody talking about the dumber problem underneath: port numbers are the wrong handle for a service. Names are stable. Ports aren't.

There's a macOS menubar app called localdock that gives dev servers stable names instead of ports — the author says 30 people pay $9 for it. macOS only. I live on Windows and Linux, so I built the tiny version of that idea as a stdlib-only Python CLI: portmap.

What it does 

pip install portmap-cli

portmap name api 3000
portmap run api -- npm run dev   # launches with $PORT set to the mapped port
portmap get api                  # -> 3000
Enter fullscreen mode Exit fullscreen mode

That's the whole pitch. Bindings live in ~/.portmap.json. An agent never guesses again:

PORT=$(portmap get api)
curl http://127.0.0.1:$PORT/health
Enter fullscreen mode Exit fullscreen mode

The part I'm happiest about: portmap run records the child pid, and portmap watch polls every 5 seconds resolving each tracked pid's actual listening ports — via /proc/net/tcp on Linux, netstat -ano on Windows. If your dev server restarts on a new port, the mapping follows it automatically. portmap serve wraps the same watcher in a tiny http.server dashboard so you can see the name → port table live.

What it deliberately doesn't do

Honest limitations, because this is a 400-line stdlib script, not a platform:

  • Polling delay. Detection happens on the next poll (default 5s). Inside that window, get can return a stale port.
  • Auto-follow needs portmap run. A bare portmap name api 3000 can only be probed up/down. If that server restarts elsewhere, portmap can't know where it went — there's no pid to track.
  • Naming only, not session management. Agent Deck, Claude Control and friends already own the multi-session panel. This is the smaller cut: just the port naming.
  • $PORT cooperation. The tool sets PORT; your server has to respect it. Most dev servers do; hardcoded ones don't.
  • Windows/Linux first. macOS falls back to TCP probing. localdock already serves macOS well — this fills the other two.

Try it

GitHub: https://github.com/hahahahahahahahah6/portmap (MIT)

pip install portmap-cli
portmap name api 3000
portmap run api -- npm run dev
portmap serve   # http://127.0.0.1:8471
Enter fullscreen mode Exit fullscreen mode

If you run multi-agent setups, I'd genuinely like to know: does the pid-tracking approach survive your restart patterns? Issues welcome.

Top comments (0)