Netwatch TUI (netwatchpy)

A TUI (Text-based User Interface) for monitoring network usage in real-time, with support for data limits and desktop notifications.

Features

• Real-time Dashboard: A clean, terminal-based dashboard showing total download, upload, total usage, and live combined current speed.
• Smart Quota Dashboard & Burn-Rate ETA: Set data caps (e.g., -l 10GB) with a real-time progress bar, remaining balance, and live countdown (ETA) calculated from active burn rate.
• Per-Interface Monitoring: Inspect bandwidth, upload/download speeds, and live 2D activity graphs segmented per active network adapter (e.g., Wi-Fi, Ethernet) with automatic loopback filtering.
• Universal Desktop Notifications: Native alerts across Windows (WinRT Toast with custom icon), macOS (AppleScript Notification Center), and Linux (D-Bus / notify-send) when reaching 80% and 100% data thresholds.
• Historical Analytics: View your usage trends for the last 24 hours with hourly breakdown, peak hour identification, and traffic statistics including download/upload percentages and average usage.
• Crash-Proof Database: Powered by SQLite with Write-Ahead Logging (WAL) to ensure your data is safe even if your PC loses power.
• Automated Data Retention & Downsampling: Automatically compresses older records into hourly averages (min, max, average speeds) and purges raw records older than the retention threshold (default: 7 days) to prevent database bloat.
• Smart Units: Toggle between Bits (Mbps) and Bytes (MB/s) instantly with Ctrl+B to match ISP speeds or file sizes.
• Optimized TUI Experience: Responsive, non-scrolling footer keybindings built for standard 80-column viewports and debounced top-bar status feedback.
• Command Palette & Dark Mode: A modern TUI experience with a built-in command palette (Ctrl+P) and dark mode support (Ctrl+D).
• Auto-Migration: Automatically detects and imports data from older versions (quota.json) so you never lose history.
• Cross-Platform: Runs seamlessly on Windows, macOS, and Linux.

Installation

Option 1: Standalone Binary (Easiest)

No Python required.

1. Download netwatch-windows.exe from the Releases Page.
2. Basic Usage: Double-click the file to start monitoring immediately.
3. Advanced Usage: To set limits (e.g., -l 10GB), open your terminal (PowerShell/CMD) in the download folder and run:

   .\netwatch-windows.exe -l 10GB
   

Option 2: Install via PyPI (Recommended for CLI)

Designed for Python 3.8+ and distributed on PyPI for simple installation with pip.

pip install netwatchpy

Usage

Once installed, the netwatch command will be available in your terminal.

To start the monitor (monitors all interfaces):

netwatch

To see all available options and help:

netwatch --help

Command-Line Arguments

You can control the monitor with these arguments:

• -h, --help

  • Shows the help message and all options.

• -i INTERFACE, --interface INTERFACE

  • Monitors a single, specific network interface (e.g., -i "Wi-Fi"). Defaults to "all".

• -l LIMIT, --limit LIMIT

  • Sets a data cap and shows a progress bar (e.g., -l "10GB" or -l "500MB").

• --log LOG

  • Saves all network activity to a specified CSV file (e.g., --log "usage.csv").

• --retention-days RETENTION_DAYS

  • Sets the retention policy in days for granular 1-second records (default: 7). Records older than this are rolled up into hourly summaries before purging.

Examples

Set a 10GB data limit:

netwatch -l "10GB"

Set custom data retention (e.g., 14 days):

netwatch --retention-days 14

Monitor a specific interface ("Wi-Fi") and log to a file:

netwatch -i "Wi-Fi" --log "my_usage.csv"

In-App Keybindings

• Ctrl+P: Open the Command Palette
• Ctrl+D: Toggle Dark / Light Theme
• Ctrl+B: Toggle Unit format between Bits (Mbps) and Bytes (MB/s)
• R: Refresh the 24-hour history chart and analytics
• Ctrl+R: Reset all counters and database records to zero
• Ctrl+S: Show auto-save status (data is continuously auto-saved to SQLite)
• Ctrl+Q: Quit the application safely

Understanding the Interface

1. Live Monitor Tab

This is the default view. It shows:

• Summary Cards: Four live telemetry cards displaying Total Downloaded, Total Uploaded, Total Bandwidth (combining session usage and stored history), and Current Speed (live combined upload and download throughput).
• Smart Quota Dashboard & Burn-Rate ETA: When a data cap is configured (-l), a compact 3-row dashboard appears above the activity log:
  • Usage Limit Header: Displays the target limit (e.g., Usage Limit: 10.00 GB).
  • Dynamic Progress Bar: Real-time visual progress bar tracking data consumption. Automatically shifts color to yellow at 80% and red at 100%.
  • Live Telemetry Badge: A compact status badge reporting exact remaining data (e.g., 1.2 GB remaining), percentage consumed ((88.0%)), active burn-rate speed (• 4.5 MB/s), and dynamic countdown ETA forecaster (• ETA: 4m 27s, or • ETA: Idle when no active traffic is flowing).
• Live Activity Table: A scrolling table recording second-by-second download and upload speeds.

2. Per-Interface Tab

A split-pane view displaying segmented metrics for each active network interface:

• Sidebar (Left): Selectable list of active interfaces (virtual and loopback connections are automatically filtered out).
• Metrics Cards (Right): Current download/upload speeds, session totals, and hardware adapter totals for the selected interface.
• Real-time Activity Graph: An uncluttered 2D waveform chart plotting live traffic trends (█ = Download, ░ = Upload).

3. History Tab (24h)

This tab visualizes your traffic over the last 24 hours.

• Traffic Summary: Displays total upload/download with percentages, peak hour, and average usage per hour.
• Hourly Breakdown: Each row represents a 1-hour block of time (e.g., 14:00 covers 2:00 PM to 2:59 PM).
• The Bar:
  • Solid Block (█): Represents Download traffic.
  • Shaded Block (░): Represents Upload traffic.
• Peak Hour: Marked with a (PEAK) tag indicating the hour of highest traffic volume.
• Total: The text on the right shows the exact data transferred during that hour.

Tip: Press r at any time to refresh the history chart with the latest database records.

Desktop Notifications

Netwatch provides native, cross-platform notifications when monitoring data limits:

• 80% Quota Warning: Triggered once total traffic reaches 80% of your configured limit.
• 100% Quota Exceeded: Triggered immediately when your limit is reached.
• Platform Integration:
  • Windows: Native WinRT Toast notifications with the Netwatch emblem icon embedded in the attribution banner via Windows Shell AppUserModelId registration.
  • macOS: Native AppleScript (osascript) Notification Center alerts.
  • Linux: Desktop notifications via D-Bus with automatic fallback to notify-send.

Bug Reports & Feature Requests

Found a bug or have a great idea? Please open an issue on the GitHub repository.

License

This project is licensed under the MIT License.