GitHub - pyjeebz/ports: See what's running on your machine, by project — and kill it by name. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
pyjeebz
ports
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>41 Commits<br>41 Commits
.github
.github
internal/inspect
internal/inspect
web
web
.gitignore
.gitignore
.goreleaser.yaml
.goreleaser.yaml
LICENSE
LICENSE
README.md
README.md
go.mod
go.mod
go.sum
go.sum
install.sh
install.sh
main.go
main.go
View all files
Repository files navigation
ports
See what's running on your machine, by project — and kill it by name.
ports.tools · Docs · Releases
ports answers one question, instantly and with zero configuration: what is running on this machine right now, and what does it belong to?
$ ports<br>PORT PROCESS PROJECT UPTIME<br>3000 Next.js ~/projects/shop 14m<br>5432 PostgreSQL docker: shop-db 2d<br>8000 FastAPI ~/projects/shop 14m<br>5173 Vite ~/projects/admin 3h
$ ports kill shop<br>✓ stopped Next.js (:3000)<br>✓ stopped FastAPI (:8000)
$ ports free 3000<br>✓ killed Next.js (pid 48391) — port 3000 is free
Why
Every developer knows this dance:
Error: Port 3000 is already in use.
$ lsof -i :3000<br>COMMAND PID<br>node 48391
$ kill -9 48391
And still nobody knows what PID 48391 was. React? Next.js? A dev server from<br>yesterday? The database you actually needed? Ports and PIDs are how the<br>operating system sees your machine — they are not how you see it. You see<br>projects: a frontend, an API, a database that belong together.
Existing tools (lsof, kill-port, fkill) stop at the PID layer — they can<br>kill a number, but they can't tell you what the number is. ports exists to<br>add the missing context: which framework a process is, which project directory<br>it belongs to, which container is really behind docker-proxy, how long it has<br>been running. That context is what turns "kill a random PID and hope" into<br>"stop yesterday's dev server, keep the database."
What it does
Lists every listening port with the framework, project directory, and uptime — not just a PID
Groups processes into the applications they belong to, so frontend :3000, api :8000, and db :5432 read as one project
Unwraps Docker , naming the real container and compose service instead of docker-proxy
Stops things safely by name — ports kill , ports free — with graceful termination before force
Finds things — ports find postgres → 5432
Speaks JSON (--json) so scripts and coding agents can ask what's running
Principles
Observer, never a runner — it never starts, supervises, or installs anything. Read-only plus targeted kill. There are plenty of process managers; this is not one, and it never will be.
Zero config — no manifest, no daemon, nothing to declare. All context is inferred from the machine itself. Useful sixty seconds after install, on a machine in whatever state it's in.
Local-first — a single static binary. No cloud, no accounts, no telemetry.
Install
Homebrew (macOS):
brew install pyjeebz/tap/ports
Scoop (Windows):
scoop bucket add pyjeebz https://github.com/pyjeebz/scoop-bucket<br>scoop install ports
curl (Linux, macOS):
curl -fsSL https://ports.tools/install | sh
Or grab a binary from the releases page, or go install github.com/pyjeebz/ports@latest.
Full documentation lives at ports.tools/docs.
About
See what's running on your machine, by project — and kill it by name.
Resources
Readme
License
MIT license
Uh oh!
There was an error while loading. Please reload this page.
Activity
Stars
stars
Watchers
watching
Forks
forks
Report repository
Releases
v0.1.0
Latest
Jul 13, 2026
Packages
Uh oh!
There was an error while loading. Please reload this page.
Contributors
Uh oh!
There was an error while loading. Please reload this page.
Languages
TypeScript<br>51.4%
Go<br>30.5%
CSS<br>15.0%
Shell<br>2.7%
JavaScript<br>0.4%
You can’t perform that action at this time.