AI-powered network monitor. Detects packet loss via ICMP ping, triggers automatic packet captures, and uses Claude or Grok to diagnose the root cause and suggest remediation.
Open your browser, configure everything in the GUI, and get plain-English analysis of exactly what went wrong on your network.
- Continuous ping monitoring — tracks loss % per target in a rolling window
- Automatic packet capture — triggers tshark/tcpdump the moment loss crosses your threshold
- Pre-buffer capture — always-on ring buffer captures the seconds before the outage is detected, so you never miss the start of an event
- AI analysis — sends the capture summary to Claude (Anthropic) or Grok (xAI) for root-cause analysis and remediation steps
- Browser GUI — full configuration, live status, event log, and pcap download from a local web interface
- Cross-platform — macOS, Windows, and Linux; pre-built binaries for macOS and Windows
| Platform | Download |
|---|---|
| macOS | netwatch-macos (latest) |
| Windows | netwatch-windows.exe (latest) |
All releases: github.com/cmdlabtech/Netwatch/releases
macOS — see the macOS note below before running.
Windows — the .exe bundles tshark and the Npcap installer; no Wireshark install required. On first launch, right-click → Run as administrator so the bundled Npcap installer can complete (silent, one-time). After that, capture works without admin because Npcap is configured for non-admin access.
Requires Python 3.11+. Dependencies install automatically on first run.
python3 netwatch.pyThe browser opens automatically at http://127.0.0.1:8765 (or the next available port if 8765 is reserved by the OS).
| Requirement | Notes |
|---|---|
| Python 3.11+ | Only needed when running from source |
| tshark (Wireshark) | Bundled inside the Windows .exe. Required separately when running from source, or for the macOS binary (macOS/Linux can also use tcpdump) |
| Npcap | Bundled inside the Windows .exe and silently installed on first run. Not needed on macOS/Linux |
| Anthropic or xAI API key | Enter in the GUI — stored locally in ~/.netwatch.conf |
| Admin / root privileges | Required on macOS/Linux. On Windows: needed once on first launch so Npcap can install (silent, with non-admin capture enabled); subsequent runs do not need admin |
The pre-built Windows .exe bundles tshark — no installation needed. If you're running from source:
- macOS:
brew install wiresharkor download from wireshark.org - Windows: install Wireshark — tshark is included. During the Npcap component of that install, uncheck "Restrict Npcap driver's access to Administrators only" to avoid needing to run as Administrator.
- Linux:
sudo apt install tsharkorsudo dnf install wireshark-cli
On macOS/Linux you can also grant your user BPF access so you don't need sudo every time:
# macOS (Wireshark installs this helper)
sudo /Library/Application\ Support/Wireshark/ChmodBPF/Install\ ChmodBPF.app/Contents/MacOS/Install\ ChmodBPF
# Linux (add yourself to the wireshark group)
sudo usermod -aG wireshark $USER # then log out and back inAll settings are available in the browser GUI. They are saved to ~/.netwatch.conf.
| Setting | Default | Description |
|---|---|---|
| Targets | 8.8.8.8, 1.1.1.1 |
Hosts to ping |
| Interface | en0 / Ethernet / eth0 |
Capture network interface |
| Egress interface | (OS default) | Interface used for AI API calls (useful if your LAN and WAN are on separate interfaces) |
| Ping interval | 1 s | How often to ping each target |
| Loss threshold | 20% | Loss % that triggers a capture |
| Window size | 10 pings | Rolling window for loss calculation |
| Capture duration | 30 s | How long to capture after a trigger |
| Cooldown | 120 s | Minimum time between captures for the same event |
| Pre-buffer | 10 s | Seconds of always-on ring buffer prepended to each capture |
| AI provider | Anthropic | Choose between Claude (Anthropic) or Grok (xAI) |
| Claude model | claude-opus-4-7 |
Any Anthropic model slug |
| Grok model | grok-3-mini |
Any xAI model slug |
The macOS release is a plain Unix executable, not a .app bundle. This is intentional.
A .app bundle requires Apple code-signing and notarization to pass Gatekeeper without prompts. Distributing an unsigned .app means users must navigate to System Settings → Privacy & Security and click "Open Anyway" — a clunky and confusing flow. A raw binary avoids that dialog entirely when launched from the terminal.
First run after downloading:
macOS quarantines files downloaded from the internet. Remove the quarantine flag before running:
xattr -d com.apple.quarantine ./netwatch-macos
chmod +x ./netwatch-macos
sudo ./netwatch-macos # sudo needed for packet captureOr right-click → Open in Finder, which also clears the quarantine flag.
pip install pyinstaller anthropic flask
pyinstaller --onefile --name netwatch --icon icon.icns --strip --clean netwatch.py
# output: dist/netwatchThe Windows build bundles tshark + DLLs and the Npcap redistributable installer so end users do not need Wireshark.
Prerequisites on the build machine:
- Install Wireshark —
build.batharveststshark.exeand its DLLs fromC:\Program Files\Wireshark. - Download the Npcap installer and save it to
tools\npcap-installer.exe(relative to the repo root).
Then:
build.bat
# output: dist\netwatch.exeBoth tools\wireshark\ and tools\npcap-installer.exe are gitignored — they live only on the build machine.
- Ping loop — NetWatch pings each target every second and records the result in a per-target rolling window.
- Loss detection — when loss in the window crosses the threshold, a capture is triggered.
- Pre-buffer freeze — the always-on ring buffer is frozen and prepended to the capture so the packets that preceded the outage are included.
- Capture — tshark or tcpdump records traffic on the configured interface for the capture duration.
- AI analysis — the capture summary is sent to Claude or Grok with a structured prompt asking for root-cause analysis and remediation steps.
- Results — the analysis appears in the browser GUI and the raw pcap is available for download.
MIT