iterm-port-status

Small iTerm2 status bar widget for macOS: shows TCP listening ports and the process name on each port (via lsof). Updates in the background while you work.

Requirements

• macOS
• iTerm2 with the Python API enabled
• Shell choice (zsh, bash, etc.) does not matter; this is not a shell plugin

Install

Option A — install script

git clone https://github.com/Hexacosidedroid/iterm-port-status.git
cd iterm-port-status
./install.sh

Option B — manual copy

Copy listening_ports_status.py to:

~/Library/Application Support/iTerm2/Scripts/AutoLaunch/

Enable Python API

1. Open Settings → General → Magic
2. Turn on the Python API option (wording may vary slightly by iTerm2 version)
3. Quit iTerm2 completely (⌘Q) and open it again

If the widget misbehaves after an update: Scripts → Restart All Daemons.

Add the widget to the status bar

1. Settings → Profiles → [your profile] → Session
2. Enable Status bar
3. Click Configure Status Bar
4. Scroll to the bottom of the component list — custom Python components are listed last
5. Drag Listening ports into Active Components
6. Optional: select it and use Configure Component for refresh interval and max ports

What it shows

• One line like: nginx:443 · ssh:22 · com.docker…:5678
• TCP LISTEN only (not UDP, not outbound connections)
• Process is the command name from lsof, not PID
• Long names are shortened (with …); commas in names are replaced so the line stays readable
• If there are more ports than the Max ports setting, the rest are summarized as +N

Configuration (component knobs)

Knob	Meaning
Refresh, sec	How often lsof is run (default 5). Lower = fresher data, slightly more CPU.
Max ports	Maximum number of ports shown before +N.

The status bar is polled about once per second; lsof is still rate-limited by Refresh, sec.

Troubleshooting

Problem	What to try
Component not in the list	Enable Python API, restart iTerm2, scroll down in the component picker, Restart All Daemons.
Empty or incomplete list	Some listeners need elevated permissions; macOS Full Disk Access for iTerm2 can help in edge cases.
Script errors	Check iTerm2’s script log / console under the Scripts menu (name varies by version).

Files

File	Role
listening_ports_status.py	AutoLaunch daemon + status bar registration
install.sh	Copies the script into Scripts/AutoLaunch

Forking

If you publish a fork, change COMPONENT_ID in listening_ports_status.py to a unique reverse-DNS string so it does not clash with other installs.

License

MIT — see LICENSE.