# wharfy

See who is listening on your dev ports — and which app or AI agent started
them — then kill them safely. CLI + MCP server. macOS.

```
$ wharfy list
PORT   PID    USER      PROCESS ← PARENTS
3000   51530  egebilge  node ← claude ← zsh ← Terminal
3001   51612  egebilge  node ← cursor ← launchd
5432   1201   egebilge  docker: papyro-app-db-1
```

The parent chain answers the question other port killers can't: *who opened
this?* A port started by Claude Code shows `claude` in the chain; one started
by Cursor shows `cursor`.

## Install

```sh
npm install -g wharfy
```

## CLI

```sh
wharfy list             # human-readable table
wharfy list --json      # machine-readable
wharfy kill 3000        # SIGTERM, then SIGKILL after 2s if it won't die
wharfy kill --all-dev   # clear every dev port at once
wharfy kill 3000 --tree # stop the whole npm-run-dev tree, not just the leaf
wharfy wait 3000        # block until the port answers (CI, scripts)
```

`kill` exits 1 when nothing listens on the port.

## MCP server (for AI agents)

Claude Code:

```sh
claude mcp add wharfy -- npx -y wharfy mcp
```

Cursor — `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "wharfy": { "command": "npx", "args": ["-y", "wharfy", "mcp"] }
  }
}
```

Tools:

- `list_ports` — listening TCP ports with owning process, user, parent chain,
  project name (read-only)
- `check_port` — who owns one port
- `kill_process` — stop whatever listens on a port; `tree` and `force` options
  (destructive, annotated as such — your client will confirm)
- `wait_for_port` — block until a server answers
- `suggest_free_port` — next free port from a preferred one
- `exposure_report` — which servers are bound to 0.0.0.0 and reachable from
  your LAN

## Menu bar app

A native macOS menu bar companion — port list with real app icons, live
CPU/RAM, LAN-exposure warnings, safe tree-kill, Docker awareness:
**[wharfy.dev](https://wharfy.dev)**

## Why not `kill-port`?

`kill-port` sends `kill -9` immediately through a shell pipeline and hasn't
been updated since 2022. wharfy parses `lsof -F` machine output in-process,
terminates gracefully (SIGTERM → 2s → SIGKILL), validates input, and tells
you who owned the port.

macOS only. MIT.