Metadata-Version: 2.4
Name: portlist-tui
Version: 1.2
Summary: Every port on this machine, and where it came from. A terminal program.
Author: Portlist contributors
License: MIT License
        
        Copyright (c) 2026 portlist contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://mr-hunt-007.github.io/portlist/
Project-URL: Source, https://github.com/Mr-hunt-007/portlist
Project-URL: Issues, https://github.com/Mr-hunt-007/portlist/issues
Project-URL: Changelog, https://github.com/Mr-hunt-007/portlist/blob/main/CHANGELOG.md
Keywords: ports,netstat,lsof,tui,terminal,devtools,localhost,developer-tools,process-monitor,curses
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: windows-curses>=2.3; sys_platform == "win32"
Dynamic: license-file

<h1 align="center">portlist</h1>

<p align="center">
  <strong>Every port on this machine, and where it came from.</strong><br>
  A terminal program. No web UI, no dashboard, no server, no dependencies.
</p>

<p align="center">
  <a href="https://mr-hunt-007.github.io/portlist/">Website</a> &middot;
  <a href="docs/USAGE.md">Usage</a> &middot;
  <a href="CHANGELOG.md">Changelog</a> &middot;
  <a href="https://github.com/Mr-hunt-007/portlist/issues">Issues</a> &middot;
  <a href="LICENSE">MIT</a> &middot;
  <a href="https://buymeacoffee.com/mr.hunt.007">Buy me a coffee</a>
</p>

```
 PORTLIST  devbox   12 listening  2 off-box  2 need attention              21:20:37
  1 Services(12)  2 Exposed(2)  3 Attention(2)  4 Leftovers(5)  5 Agents(3)  6 Containers(0)  7 Sessions(8)  8 System

 PORT    SERVICE             PROJECT           REACHABLE       RISK      STARTED BY
 :3000   Next.js             storefront        Localhost only   12 Info  Claude Code 2h
 :5173   Vite                admin-ui          Localhost only   12 Info  terminal 5h
 :8787   Python http.server  data-export       All interfaces   71 High  Claude Code 5d
 :9050   Tor                 /opt/homebrew     Localhost only   12 Info  launchd 24d

 j/k move   h/l pane   tab view   enter detail   O open   / search   f free port   V vibe   q quit
```

Twelve things are listening. You started three of them today and you cannot name
the rest.

## What problem does it solve

`lsof -i` and `netstat` answer *what is bound to this port*. That was the whole
question when a machine ran two servers you started by hand. It is not the
question any more, because most of what is listening on a developer laptop was
started by something else: an agent session, an editor, a container, a service
manager, or you, on Tuesday, in a directory you have since forgotten.

The questions that are actually in the way:

| you ask | `lsof` says | portlist says |
|---|---|---|
| what is on :8787? | `Python, pid 96798` | a static file server, started by a Claude Code session, in `~/code/data-export` |
| who started it? | nothing | that session, and whether it has since exited |
| can anyone reach it? | a bind string like `0.0.0.0` | what answered when it connected to this machine's real address |
| is it still needed? | how long it has been *up* | how long it has been *unused*, measured over time |
| is it safe to kill? | nothing | what depends on it, what it depends on, and the command to stop it |

Three situations it was built for:

**"Address already in use."** Something holds :3000 and you did not start it.
Was it this morning's agent session, a container, or a dev server from last
Tuesday that never died? portlist names it, and if you just want a port that is
free now and not spoken for later, `f` gives you one.

**An agent left the lights on.** Coding agents start servers and move on. The
session exits, the server does not, and nothing on the machine remembers which
session it belonged to. portlist writes a launch record the first time it sees a
service and never rewrites it, so the answer survives both the agent exiting and
the service being restarted by something else.

**Bound to the world by accident.** `0.0.0.0` in a config file is a claim. The
only honest answer comes from connecting to this machine's real address and
seeing what answers, which is what the `REACHABLE` column is.

And the rule underneath all of it: **it never dresses a guess as a fact.** A
service that was already listening before portlist first looked has *unknown*
origin and says so, rather than inheriting a label from whatever owns the port
now. "The container engine did not answer" is never rendered as "no containers".

## Install

**Homebrew** (macOS, Linux)

```sh
brew tap Mr-hunt-007/portlist https://github.com/Mr-hunt-007/homebrew-portlist
brew trust mr-hunt-007/portlist      # Homebrew asks this of every third-party tap
brew install portlist
```

**pip or pipx**, anywhere. pipx is the simplest route on Windows, because it
brings `windows-curses` along:

```sh
pipx install git+https://github.com/Mr-hunt-007/portlist
pip  install git+https://github.com/Mr-hunt-007/portlist
```

**One line**, into `~/.local`, no root and nothing system-wide:

```sh
curl -fsSL https://mr-hunt-007.github.io/portlist/install.sh | sh
```

**From source**, which needs nothing but Python:

```sh
git clone https://github.com/Mr-hunt-007/portlist && cd portlist && python3 portlist.py
```

Then run `portlist`.

<sub>Not yet published: `pip install portlist-tui` (the artifacts are built and
pass `twine check`, but nothing has been uploaded) and `winget install` (the
manifests are in `packaging/winget/`, not submitted). The name `portlist` on
PyPI belongs to an unrelated package, which is why the distribution is
`portlist-tui` while the command stays `portlist`.</sub>

## The dashboard

`0`, and it is where portlist opens. Everything about the machine on one screen,
so a single screenshot tells the whole story.

```
  MACHINE                                           EXPOSURE                    AGENTS                      CONTAINERS
     ·  ●  ●         ·  ●  ●         ◉  ●  ●        LISTENING      16           Claude Code    14           ENGINE         docker
   ·         ●     ·         ●     ●         ●      EXPOSED        2            terminal       1            STATE          no answer
  ·    36%    ◉   ◉    85%    ●   ●    96%    ●     NEEDS WORK     2            launchd        1                           count unknown
   ·   CPU   ·     ●   RAM   ●     ●  DISK   ●      UNKNOWN ORIGIN 12                                                      not zero
     ·  ·  ·         ●  ●  ●         ●  ●  ●
  LOAD  3.56 3.37 3.64

  LISTENING  14 services                                                                                      Tab  next section
    PORT    SERVICE               PROJECT           STARTED BY          REACH           RISK
  ● :7337   Grafana               metrics           terminal            Localhost only  12 Info
  ○ :8000   Python http.server    analytics         Claude Code         Localhost only  12 Info
  ○ :8787   Python http.server    data-export       Claude Code         All interfaces  71 High

  SELECTED SERVICE                                                          │ ACTIVITY
                                                                            │
  Grafana :7337                                                             │ 22:52:49 · Bun on :10065 stopped listening
  ~/code/metrics                                                            │ 22:23:58 · Bun opened on :57155 (loopback)
                                                                            │
  REACH      Localhost only                                                 │ CPU
  PID        9561   Python                                                  │ ▃▃▄▃▃▂▃▄▅▄▃▃▃
  LAST USED  in use now                                                     │ MEMORY
                                                                            │ ▇▇▇▇▇▇▇▇▇▇▇▇▇
  RISK  71 / 100   High                                                     │
    +42   Listening on all interfaces (0.0.0.0)                             │
    +10   No authentication seen and reachable off-box                      │

  ● 2 exposed    ◆ 2 need attention    ⚠ 12 unknown origin    ◉ 3 agents    firewall on
```

**Tab** moves to the next view, in the same order as the number keys, and
**shift-Tab** goes back. **`h`** and **`l`** (or the arrows) move between the
dashboard's panes, and `j`/`k` move inside whichever has focus.

The three dials are live: each ring is twelve segments, the leading one pulses,
and the ring eases round rather than jumping when the reading changes. An
unmeasured value draws an empty ring and says so instead of resting at zero.

Under every card and across the table runs the same travelling wave, and its
**amplitude and speed are the reading**: a quiet machine ripples slowly and
shallowly, a busy one moves faster and taller. It is a sine, not a history, and
it is never drawn where a history belongs; the sparklines plot real samples. A
card with nothing to measure draws a flat line of dots rather than a wave at
zero, because a flat wave still reads as a measurement of zero, and "not
measured" is not zero.

The risk score is never a bare number. The pane lists what it was made of, so
`71 High` is auditable rather than magical, and `⚠ 12 unknown origin` is counted
precisely so those services are not quietly attributed to whatever owns the port
now.

## Ten views

| key | view | what it answers |
|-----|------|-----------------|
| `0` | dashboard | everything at once, and where it opens |
| `1` | services | everything listening, with who started it |
| `2` | exposed | reachable from beyond this machine |
| `3` | attention | critical, high and medium risk |
| `4` | leftovers | looks abandoned, with the measurements behind the guess |
| `5` | agents | grouped by the agent, editor or terminal that started it |
| `6` | containers | by compose project, and the host ports they hold |
| `7` | sessions | coding-agent sessions, what they were about, context used |
| `8` | system | this machine: load, memory, disks, network, exposure |
| `9` | graph | who started what, where it runs, and what it exposes |
| `V` | vibe | the ambient screen, for the second monitor |

Views 5 and 6 group rather than filter. Every view is a different question asked
of one scan, not a different scan.

## Keys

```
j / k, arrows   move                    tab shift-tab   the next view, the
h / l           the dashboard's panes                   same order as 0-9
enter, o        detail pane             /   search
O               open it in a browser    f   a port that is free now, and not
                (ctrl+enter too, where      spoken for by anything later
                the terminal sends it)  a   animation      V   vibe mode
0-9             views                   r   rescan now     ?   keys    q  quit
```

macOS never delivers Cmd+Enter to a terminal program, so `O` is the binding that
always works.

## The sessions you left open

Ten agent windows, none of them closed, and no way to tell which is which.

Press **7**. Open sessions first, because those are the only rows you can act
on; everything under them is a transcript nobody is holding:

```
 TOOL     WHAT IT WAS ABOUT                    PROJECT      CONTEXT  VS BIGGEST  LAST USED
 4 agent processes running  -  30 transcripts on disk
     Claude Code      max - default max 20x
     Codex            not signed in

 6 open right now  -  2.9M tokens between them  -  oldest untouched 5h
 * claude Refactor the billing webhook retries  payments       215k  ██░░░░░░    2s ago    4 here
 * claude Port the admin table to components    admin-ui       904k  ████████    17m ago   4 here
 * claude Trace the flaky integration test      api            479k  ████░░░░    26m ago   4 here

 24 left on disk, no process behind them
   claude Split the worker into two queues      worker         935k  ████████    7h ago
   claude Make the search endpoint paginate     docs           193k  ██░░░░░░    9h ago
```

The bar compares each session with the **biggest one on this machine**, and
with nothing else. A transcript records the tokens a turn carried; it never
records the model's context limit, so portlist will not print a percentage of a
window it cannot read.

`enter` opens the rest of it - the first prompt you typed, where the session got
to, and how to close it:

```
 context       903,802 tokens on the last turn  -  214 turns
 last active   28 Aug 04:14  (17m ago)
 running       pid 14502
 close it      kill 14502
 first prompt  the stripe webhook retries twice on 5xx, work out why and fix...
 last prompt   run the migration against staging first
```

When several agents share one directory it says so instead of choosing:

```
 running       pid 9316, 5864, 30000, 43725 - more than one agent is in this
               directory, so which of them is this session cannot be told from outside
 close it      from its own window - the line above says why a pid cannot be picked for you
```

A `kill` that might close the wrong window is worse than no command at all.

Six tools, each read from the store it already writes:

| | |
|---|---|
| **Claude Code** | `~/.claude/projects/**/*.jsonl` |
| **Codex** | `~/.codex/sessions/**/rollout-*.jsonl` |
| **GitHub Copilot CLI** | `~/.copilot/session-store.db`, which keeps its own summary |
| **VS Code chat** | `.../Code/User/workspaceStorage/*/chatSessions/*.jsonl` |
| **Cursor** | the same layout under `Cursor/`, because it is a VS Code fork |
| **Gemini CLI** | `~/.gemini/tmp/*/logs.json`, where a build writes one |

Each gives the generated title, the first prompt you typed, the project, the
model, the turn count, and where available the **context it is carrying** - the
token total from the last turn, which is the number that decides what to clear.

It also shows which plan each tool is signed in under, so "which account burned
this week's quota" is answerable:

```
  Claude Code      max - default max 20x
  Codex            not signed in
  GitHub Copilot   signed in
  Gemini           signed in
```

Live sessions are matched to running agent processes by working directory. Where
several agents share one directory it says so rather than guessing.

**Prompts never leave the machine.** portlist has no server and no network code
at all, so there is nowhere for them to go. Account details are narrower still:
the plan and the organisation, never the address or the account id.

It never reads a whole transcript either - they reach eight megabytes. The head
has the first prompt and the directory, the tail has the title, the latest usage
and the last activity. Sixty sessions in a tenth of a second.

## The graph

`9`. Who started what, where it runs and what it exposes, laid out the way a
terminal draws a layered graph well:

```
  STARTED BY            PROJECT             PROCESS           PORT  AND SERVICE          REACHABLE FROM
  started work in ──▸   runs ──▸            listens ──▸       confirmed on ──▸

  ◆ Claude Code       ├─analytics         ──Python pid 6810 ──:8000   Python http.serv ──Localhost only
  │                   ├─data-export       ──node pid 77259  ──:8422   unidentified     ──Localhost only
  │                   │                   ──Python pid 96798──:8787   Python http.serv ──All interfaces  confirmed on 192.168.0.2
  │                   ├─metrics           ──bun pid 32016   ──:48744  Bun              ──Localhost only
  │                   └─scanner           ──Python pid 67222──:8787   FastAPI / Uvicorn──Localhost only
  ◇ launchd           └─no project        ──tor pid 58508   ──:9050   Tor              ──Localhost only

  ◆ an agent session   ◇ something else   10 of 12 services were started by an agent
```

One line is one service, and a parent is printed once and carried down with a
rule, which is what makes the sharing visible: eleven services under one agent
session, four in one project. The edge names are the ones the web version uses,
so both surfaces describe the machine with one vocabulary.

Narrow terminals get the same graph as headed groups, because that is what a
tree looks like when it runs out of width.

## Vibe mode

Press **V**, or leave it alone for thirty seconds:

```
                              P O R T L I S T

                                LOCAL NETWORK

                                   ○ :8787
                  :8422 ○ ·           ·           · ○ :8807
                            ·····     ·     ·····
             :8078 ○ ···················HOST···········●······ ◉ :7337
                            ·····     ·     ·····
                  :9050 ○ ·           ·           · ○ :8000

                  1 connection observed between local services
```

Seven scenes rotate: the cockpit (everything at once), a grid of every listening
service, the machine and its
meters, the network between local services, each agent and what it started,
what has actually happened lately, and **the room** - a plate that ships with
the program, drawn as characters, with the three numbers that fit placed where
it is dark. Five themes, four speeds, `t` and `s` to
cycle them, any other key to come back.

The room scene ships a picture so that it is a scene at all, but that is a
default and not a fixture: set a picture of your own and the room shows yours.
A picture of yours decorates the other six: name it on the way in with
`portlist --vibe-bg thing.png`, or drop PNGs into `~/.portlist/backgrounds/` and
press `g` inside vibe mode to walk them, with the footer naming what is showing.

`g` covers both which picture and how it is drawn:

```
none  ->  room.png as an image  ->  room.png as characters  ->  none
```

**As an image** means the terminal is handed the PNG and draws it itself, behind
the text. **As characters** is the density rendering: `b` sets how strongly it
shows, 0 to 100, and `B` decides which end of the picture becomes ink.

### Which terminal shows the real picture

Almost no terminal can draw a picture. The ones that can speak **kitty's
graphics protocol**, and portlist uses only that protocol, for one reason: it
has a z-index, and `z=-1` is the only arrangement that puts a picture *behind*
the readings. iTerm2's inline images and sixel both occupy cells, so a picture
drawn either way would cover the numbers, and a screen whose numbers are hidden
by decoration is worse than a screen with no decoration. So iTerm2 and every
sixel terminal get the character rendering too.

If the ring goes straight from `none` to *as characters*, your terminal cannot
do it. That is not a setting you are missing.

**macOS** - Terminal.app cannot, and no preference changes that. iTerm2 cannot
either, for the reason above. Install one of:

```sh
brew install --cask ghostty     # verified working, and needs no configuration
brew install --cask kitty       # the reference implementation of the protocol
brew install --cask wezterm
```

If Ghostty is the first thing you install, note that its `TERM` is
`xterm-ghostty`, which is not in the terminfo database most systems ship. Recent
versions install it for you; if portlist will not start there at all, that is
why, and this fixes it:

```sh
mkdir -p ~/.terminfo/78
cp /Applications/Ghostty.app/Contents/Resources/terminfo/78/xterm-ghostty ~/.terminfo/78/
```

**Linux** - several work. kitty and Ghostty are packaged for most distributions;
Konsole (KDE) and WezTerm implement the protocol as well.

```sh
sudo apt install kitty                 # Debian, Ubuntu
sudo dnf install kitty                 # Fedora
sudo pacman -S kitty                   # Arch
curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin
```

**Windows** - Windows Terminal speaks sixel, not this protocol, so it draws
characters. **WezTerm** is the one that works:

```powershell
winget install wez.wezterm
```

Under WSL the terminal is whatever is drawing the window, so the same rule
applies: WezTerm yes, Windows Terminal characters.

**Over ssh** it works when the terminal in front of *you* supports it, because
the escape travels down the connection like any other output. **Inside tmux** it
usually does not, unless tmux is configured to pass the escape through. The
character rendering has none of these conditions, which is why it stays the
default answer rather than a fallback.

Nothing is written to a terminal that has not said it speaks the protocol, so
being wrong about support costs a blank background rather than escape codes
across your screen. To force characters everywhere, including on a terminal that
could show the file, set `PORTLIST_NO_GRAPHICS=1` or press `g` one more step.

**Confirmed on Ghostty**, macOS, with the picture behind the readings as
intended. kitty is the reference implementation of the protocol and Konsole and
WezTerm implement it too, but I have not put eyes on those three, and terminals
differ in how completely they follow the spec. If yours honours the protocol
without the z-index the picture will sit *over* the text rather than behind it:
press `g` once more for characters, and open an issue naming the terminal.

When a service really appears while you are watching, it is marked **NEW** for a
few seconds and the strip redraws around it; when one stops listening, that is
reported too. The first frame marks nothing, because everything is new to the
screen the moment it opens and none of it is new to the machine.

**Nothing on that screen moves unless something was measured.** A dot pulses
because that service was measured busy inside the last minute. A particle
crosses an edge because a loopback connection between those two ports was
observed. Where nothing has been measured, it says so and sits still: inventing
motion would make the prettiest part of the program the one lying to you.

## What it can tell you that `lsof` cannot

- **Who started it.** Claude Code, Cursor, Codex, Copilot, Aider, Goose,
  Windsurf, a terminal, a service manager - from process ancestry first and the
  environment second. And whether that session has since exited.
- **Whether it survived a restart.** A launch record is written the first time a
  service is seen and never rewritten, so attribution outlives both the agent
  exiting and the service being restarted by something else.
- **Whether anyone is using it.** Measured over time, not inferred from uptime.
- **Whether the network can reach it**, checked by connecting to this machine's
  real address rather than reading a bind string.
- **Which container holds the port**, and which compose project it belongs to.
- **A port that is free** now and not spoken for by anything you run later.

## It never stops anything

The detail pane prints the command; you run it. There is no kill key, no daemon,
and nothing here writes to another machine.

It does open sockets, and it is worth being exact about which. It connects
*outward* to the ports on this machine to see what answers, and it binds a
candidate port for a moment to check it is free, then closes it. Neither ever
calls `listen()`, so portlist has no port of its own and nothing can connect
to it.

## Where its data lives

`~/.portlist/` - the launch ledger, use history and the recipe book. Override
with `--data-dir` or `PORTLIST_DATA`.

## Requirements

Python 3.9+ with `curses`, standard on macOS, Linux and BSD. On Windows,
`pip install windows-curses`, which `pipx install portlist` does for you. No
third-party packages on any platform otherwise, ever.

## Documentation

- [Setup](docs/SETUP.md) - every install route, and what each one puts where
- [Usage](docs/USAGE.md) - the views, the keys, and what each column means
- [Features](docs/FEATURES.md) - the full list, and how each answer is reached
- [Architecture](docs/ARCHITECTURE.md) - one scan, one model, ten views
- [Motion](docs/MOTION.md) - the animation language, and why each thing moves
- [Security](SECURITY.md) - what it reads, what it never sends
- [Contributing](CONTRIBUTING.md)

MIT.

---

If portlist saved you an afternoon of `lsof | grep`, you can
[buy me a coffee](https://buymeacoffee.com/mr.hunt.007). Entirely optional: the
tool is free, has no telemetry, and will stay that way.
