Port already in use? Find out what’s listening. Portman shows the process behind a local TCP port with one command, so you can get back to building.
View on GitHub · Releases · Report an issue
Install
On macOS, install with Homebrew :
brew install arps18/tap/portman
Requires lsof. Prebuilt binaries for Apple Silicon and Intel Macs, along with checksums, are also available on the release page
.
Find a listener
Pass the port you want to inspect:
portman 3000
You’ll see the listening process, its PID, and the address it’s bound to. Example output (with identifying details replaced):
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
Python 12345 dev 3u IPv4 0x0000 0t0 TCP 127.0.0.1:3000 (LISTEN)
Nothing listening? Portman tells you that too:
No TCP listeners found on port 3000
Use a port between 1 and 65535. A completed inspection exits with status 0, even when there are no listeners. Invalid input or an inspection failure exits with status 1.
Portman currently inspects TCP listeners on macOS. Results depend on what lsof can see with your permissions. It does not stop processes.
Use with coding agents
Coding agents with shell access can run Portman when it’s installed and on their PATH. Add this to your agent’s project instructions:
When a development server reports a port conflict, run
portman <port> to inspect its TCP listeners.
No dedicated integration is needed; Portman returns terminal output.
Releases & roadmap
v0.1.0 — First release
releasedInspect a local TCP port on macOS, with Homebrew installation and binaries for Apple Silicon and Intel Macs.
Planned next steps from the project’s roadmap. These features are not yet released, and scope may change:
| Version | Planned work |
|---|---|
| v0.2.0 | Help and version commands; clearer errors |
| v0.3.0 | List all visible TCP listeners |
| v0.4.0 | JSON output for scripts and tools |
| v0.5.0 | Stop a listener with confirmation and graceful termination |
| v0.6.0 | Linux support |
| v0.7.0 | Watch a port for listener changes |
See all releases for the latest version and downloads.
About the project
I’m building Portman as a hobby project to learn Go, testing, CLI design, and operating-system fundamentals. Small tool, real development problem.
The code is MIT licensed . Want to explore or contribute? Start with the source and development instructions , or open an issue .