netshow · interactive, process-aware network monitoring for your terminal

A quick plug for AI-Enhanced Docs

But why?

This README was written with AI assistance, and here's why that matters

As a solo dev building open source tools that many never see outside use, comprehensive documentation often wouldn't happen without AI help. Using agentic dev tools like Roo & Claude Code that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.

In this case, Sonnet 4 took a pass & a human (me) verified them 7/10/25.

✨ Features

🔍 Live TCP monitor	Refreshes every 3 s (configurable) while preserving scroll position
👤 Human-friendly service names	Shows Docker, Plex, VS Code, etc. instead of cryptic binaries
🔬 Deep process drill-down	Path, PID, cmdline, cwd, threads, CPU %, memory %, open files, active connections
🖱️ Clickable / keyboard navigation	Press `↵` or click a row for a dedicated detail screen; refresh pauses automatically
🔐 Runs privileged or unprivileged	Uses `psutil` (root) for full fidelity, falls back to `lsof` if run as a regular user
📊 Real-time metrics	Live connection counts, bandwidth monitoring with per-interface selection
🔍 Advanced filtering	Regex-powered search with live filtering across all connection fields
🔄 Smart sorting	Sort by status or process name with optimized rendering for large datasets
🎨 Modern Textual UI	Smooth scrolling, dark theme, status bar with connection count & data source
⚡ Zero-pain install	Powered by `uv` for lightning-fast dependency resolution

🚀 Quickstart

# uvx (easiest) uvx netshow Local Builds

git clone git@github.com:taylorwilsdon/netshow.git uv run netshow

💡 Tip: Without root/sudo, NetShow silently switches to lsof and still gives you most connections.

🛠️ Usage

netshow [--interval 1.0] [--no-colors]

Options

Option	Description	Default
`--interval <sec>`	Refresh rate (float)	`3.0`
`--no-colors`	Disable ANSI colors	Off

Keybindings

Key / Mouse	Action
↑ / ↓	Move cursor
↵ / Click	Open detail view
Esc / ←	Back to list
q	Quit NetShow
Ctrl+C	Force quit (hard quit)
Ctrl+R	Force refresh
e	Toggle emoji display on/off
f	Toggle filter input
/	Quick search (focus filter)
s	Sort by connection status
p	Sort by process name
i	Cycle network interface for bandwidth monitoring

Advanced Features

🔍 Filtering & Search

Press f or / to open the filter input
Supports regex patterns for advanced matching
Filters across process names, addresses, and connection status
Live updates as you type (with debouncing)

🎨 Emoji Toggle

Press e to toggle emoji display on/off for a cleaner interface
When disabled, removes all emoji prefixes from UI elements
Useful for terminals with limited emoji support or accessibility preferences
Setting persists during the session

📊 Bandwidth Monitoring

Real-time bandwidth display in the metrics bar
Press i to cycle through network interfaces (all, eth0, wlan0, etc.)
Accurate per-interface monitoring for multi-NIC hosts
Automatic fallback to global stats if interface unavailable

🔄 Smart Performance

Optimized table rendering for large connection sets (5k+ connections)
In-place cell updates to prevent flicker during sorting
Preserves scroll position and cursor during refreshes
Debounced filter input to avoid excessive updates

👩‍💻 Development

git clone https://github.com/taylorwilsdon/netshow.git
cd netshow
uv sync --extra dev

Quality Gates

pytest            # tests
ruff format .     # auto-format
ruff check .      # lint
mypy src/         # type check

📋 Requirements

• Python ≥ 3.9
• macOS or Linux
• lsof (usually pre-installed)

🤝 Contributing

Pull requests and ⭐ stars are welcome! Found a bug or have a feature request? Please open an issue.

📜 License

MIT – see LICENSE for full text.

NAME

SYNOPSIS

INFO

DESCRIPTION

README