netshow_v2_demo.mp4
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 netshow
# Local Builds
git clone git@github.com:taylorwilsdon/netshow.git
uv run netshow
Tip: Without root/sudo, NetShow silently switches to
lsofand still gives you most connections.
Usage
Options
| Option | Description | Default |
|---|---|---|
--interval |
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
for/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
eto 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
ito 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
cd netshow
uv sync --extra dev
Quality Gates
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.