netshow 0.2.2

A real-time network connection monitor with friendly service names

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 [e-mail]: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.