network-doctor
Find out why your internet feels bad, and fix it at the router.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/dav-ayman--network-doctor)HTML
<a href="/listings/dav-ayman--network-doctor"><img src="/api/listings/dav-ayman--network-doctor/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**Claude Code**
/plugin marketplace add dav-ayman/network-doctor /plugin install network-doctor@network-doctor
You get the skill and the MCP tools.
**Claude Desktop**
1. Download `network-doctor-<version>.mcpb` from [Releases](https://github.com/dav-ayman/network-doctor/releases/latest). 2. Double-click it, or go to Settings > Extensions and drag it in. 3. Click Install.
It runs locally on your computer, so it can see your real Wi-Fi and router. A cloud sandbox can't.
Then just describe the problem: *"my calls keep breaking up"*, *"why is my Wi-Fi so slow?"*, *"check my 5G router's signal"*.
There's nothing to `pip install`. It's Python 3.9+ standard library only, and runs on macOS (first class) and Linux. On macOS, `python3` comes with the Xcode command line tools (`xcode-select --install`).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 22 lines
- {
- "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
- "name": "network-doctor",
- "description": "Find out why your internet feels bad, and fix it at the router.",
- "owner": {
- "name": "dav-ayman",
- "url": "https://github.com/dav-ayman"
- },
- "plugins": [
- {
- "name": "network-doctor",
- "description": "Diagnose bad internet end to end (Wi-Fi, bufferbloat, call quality, MTU, DNS, 4G/5G signal) and read or tune home routers: Huawei, ZTE, TP-Link, ASUS, FRITZ!Box, MikroTik, OpenWrt.",
- "version": "0.1.0",
- "author": { "name": "dav-ayman", "url": "https://github.com/dav-ayman" },
- "source": "./plugins/network-doctor",
- "category": "productivity",
- "homepage": "https://github.com/dav-ayman/network-doctor",
- "license": "MIT",
- "keywords": ["network", "wifi", "router", "bufferbloat", "latency", "voip", "5g", "lte", "diagnostics"]
- }
- ]
- }
README.md · README · 141 lines
- <p align="center">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="docs/media/banner-dark.svg">
- <img alt="network-doctor: why is my internet bad? Ask Claude." src="docs/media/banner-light.svg" width="100%">
- </picture>
- </p>
- <p align="center">
- <a href="https://github.com/dav-ayman/network-doctor/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/dav-ayman/network-doctor/actions/workflows/ci.yml/badge.svg"></a>
- <img alt="Python 3.9+" src="https://img.shields.io/badge/python-3.9%2B-blue">
- <img alt="No dependencies" src="https://img.shields.io/badge/dependencies-none-brightgreen">
- <img alt="MIT" src="https://img.shields.io/badge/license-MIT-black">
- </p>
- <p align="center"><b><a href="https://dav-ayman.github.io/network-doctor/">dav-ayman.github.io/network-doctor</a></b></p>
- **network-doctor** is a [Claude Code](https://claude.com/claude-code) plugin that finds out *why* your internet feels bad, then fixes it at the router, with your approval at every step.
- > "My voice keeps breaking in meetings."
- Instead of guessing, Claude measures:
- - your Wi-Fi;
- - latency **while your connection is loaded** (the usual reason calls break);
- - call quality on the same UDP path Zoom, Teams and Meet use;
- - MTU and DNS.
- Then it logs in to your router, reading the password from your OS keychain, to read the cellular signal, Wi-Fi channels and QoS. You get ranked findings with evidence. Fixes are proposed, applied only after you say yes, backed up, and re-measured.
- <p align="center">
- <img alt="netdoc diagnose demo" src="docs/media/diagnose.gif" width="820">
- </p>
- <p align="center"><a href="docs/media/hero.mp4">▶ Watch the 1-minute overview</a></p>
- ## Install
- **Claude Code**
- ```
- /plugin marketplace add dav-ayman/network-doctor
- /plugin install network-doctor@network-doctor
- ```
- You get the skill and the MCP tools.
- **Claude Desktop**
- 1. Download `network-doctor-<version>.mcpb` from [Releases](https://github.com/dav-ayman/network-doctor/releases/latest).
- 2. Double-click it, or go to Settings > Extensions and drag it in.
- 3. Click Install.
- It runs locally on your computer, so it can see your real Wi-Fi and router. A cloud sandbox can't.
- Then just describe the problem: *"my calls keep breaking up"*, *"why is my Wi-Fi so slow?"*, *"check my 5G router's signal"*.
- There's nothing to `pip install`. It's Python 3.9+ standard library only, and runs on macOS (first class) and Linux. On macOS, `python3` comes with the Xcode command line tools (`xcode-select --install`).
- ## What it checks
- <p align="center">
- <img alt="diagnosis pipeline" src="docs/media/pipeline.svg" width="820">
- </p>
- | check | how | catches |
- |---|---|---|
- | Wi-Fi | RSSI, SNR, channel, width, neighbouring networks | weak signal, crowded 2.4 GHz, 40 MHz on 2.4 GHz |
- | Local link | router ping at 5/s | Wi-Fi dropouts, retries, bad cables |
- | **Latency under load** | call probe idle vs during upload vs during download | **bufferbloat**, graded A+ to F |
- | Call quality | UDP STUN at 10 packets/s | loss, jitter, packets too late for voice |
- | MTU | DF-ping binary search | PPPoE/VPN black holes |
- | DNS | lookup times | slow or failing resolvers |
- | Router | vendor API, read-only by default | 4G/5G RSRP/RSRQ/SINR/band, Wi-Fi config, clients, QoS/SQM |
- <p align="center">
- <img alt="call quality while uploading" src="docs/media/call-under-load.gif" width="820">
- </p>
- ## Supported routers
- | family | covers | tier |
- |---|---|---|
- | Huawei HiLink | 5G CPE 5s/Pro, B310-B818, E5577/E5785 MiFi, E3372 | ✅ verified |
- | ZTE goform | U20, MU5001, MF971 and most ZTE MiFis | ✅ verified |
- | ZTE ZXHN | H188A (verified), H298A, F670L and ISP-branded gateways | ✅ verified |
- | Huawei home gateway | HG630 V2 (verified), HG633, HG658 | ✅ verified |
- | TP-Link Archer | AX/C-series "luci" web UI (signed-AES and RSA logins) | 🧪 experimental |
- | TP-Link LTE | Archer MR200/MR600, TL-MR6400/MR6500 | 🧪 experimental |
- | TP-Link legacy | older TL-WR / Archer `/userRpm/` UI (read-only) | 🧪 experimental |
- | ASUS | ASUSWRT / Asuswrt-Merlin | 🧪 experimental |
- | AVM FRITZ!Box | TR-064 | 🧪 experimental |
- | MikroTik | RouterOS 7 REST, including LTE monitor | 🧪 experimental |
- | OpenWrt | ubus JSON-RPC (LuCI builds), SQM status | 🧪 experimental |
- **Verified** means a maintainer tested it on real hardware. **Experimental** means it was written from public protocol documentation and tested against synthetic answers.
- Have one of these routers? Run `netdoc.py router detect` and tell us if it works. That's how a family becomes verified. Full list: [docs/support-matrix.md](docs/support-matrix.md).
- <p align="center">
- <img alt="router signal readout" src="docs/media/router.gif" width="820">
- </p>
- **Router not listed?** `netdoc.py capture` saves a masked snapshot of its web API: page title, headers and API paths, with no secrets, MACs, SSIDs or public IPs. Attach it to an [Add my router](https://github.com/dav-ayman/network-doctor/issues/new?template=router-support.yml) issue. Someone can then write a driver without owning the hardware.
- ## Safety
- - **Passwords never touch the chat.** You store them yourself in the macOS Keychain or Linux Secret Service, either with `netdoc.py secret set <router-ip>` or in the terminal window that Claude Desktop opens for you. Output is masked: passwords, keys, tokens, IMEI/ICCID and serials.
- - **Passwords stay with their router.** Each stored password is tied to the router's hardware (MAC) address. Lots of networks use the same gateway IP, but your home password is never offered to the café's 192.168.1.1.
- - **No lockouts.** Routers lock the admin account after 3-10 wrong passwords. A rejected login is remembered, and netdoc refuses to try again until you fix the password and run `router unblock`.
- - **Read-only by default.** Writes show a plan first (current value, then new value). They run only with `--apply` after you approve, save a backup, and come with a one-line revert.
- - **TP-Link variants it doesn't recognise:** netdoc stops before sending the password.
- ## Try it without a router
- ```
- python3 plugins/network-doctor/skills/network-doctor/scripts/netdoc.py diagnose --demo
- ```
- `--demo` runs on a synthetic network: a 5G CPE with bufferbloat and crowded 2.4 GHz Wi-Fi. All the screenshots and videos here come from it.
- ## CLI
- Claude drives the CLI for you. You can also run it directly:
- ```
- netdoc.py diagnose [--quick] [--json] full checkup with ranked findings
- netdoc.py bloat | call [--load up|down] latency under load / call-quality probe
- netdoc.py wifi | link | ping | mtu | dns individual checks
- netdoc.py router detect | status | get | explore | drivers
- netdoc.py router write <target> k=v [--apply] plan, then apply (with backup)
- netdoc.py router revert <backup> [--apply]
- netdoc.py capture masked API snapshot for issues
- netdoc.py secret set|check|delete <ip> keychain (run it yourself)
- ```
- ## Contributing
- Drivers are single files with fixture tests. See [CONTRIBUTING.md](CONTRIBUTING.md). The most valuable contribution is **confirming an experimental driver on your router**.
- ## License
- MIT. Router vendors' names are used only to describe compatibility. This project isn't affiliated with any vendor.
plugins/network-doctor/skills/network-doctor/scripts/netdoc/mask.py · Bundled script · 88 lines · 1 finding marked
- """Masking of secrets and personal identifiers in anything netdoc prints or saves.
- Two levels:
- - secrets (always): passwords, keys, PSKs, tokens, session ids, IMEI/IMSI/ICCID/MSISDN, serial numbers.
- - identifiers (capture/share mode): MAC addresses, SSIDs, public IPs, host names, phone numbers.
- """
- from __future__ import annotations
- import ipaddress
- import re
- from typing import Any
- SECRET_KEY = re.compile(
- r"(pass(word|wd|phrase)?|pwd|psk|wpa_?key|wepkey|presharedkey|secret|token|nonce|salt|proof|"
- r"sessionid|session_id|sessiontoken|stok|sysauth|cookie|authorization|auth_?token|auth_?key|imei|imsi|iccid|msisdn|serial|sn$|"
- r"wifikey|key\d*$|_key$|^key$|pin$|puk$|apikey|private)",
- re.I,
- )
- # Keys that look like secrets by name but are harmless and useful.
- SAFE_KEY = re.compile(r"(key_?mgmt|key_?type|encryption\w*|auth_?mode\w*|authentication_?mode|beacontype|tokenexpir\w*|"
- r"password_?type|keyindex|key_?index|auth_?type)$", re.I)
- IDENT_KEY = re.compile(r"(ssid|mac|bssid|hostname|host_?name|devicename|^name$|phone|number|ipv6|wan_?ip|"
- r"public_?ip|externalip|ipaddress|ip_?address)", re.I)
- MAC = re.compile(r"\b([0-9A-Fa-f]{2}[:-]){5}[0-9A-Fa-f]{2}\b")
- IMEI_LIKE = re.compile(r"\b\d{15,20}\b")
- XML_SECRET = re.compile(
- r"<(\w*(?:[Pp]assword|PSK|Psk|psk|WpaKey|WepKey|WifiKey|PreSharedKey|[Ss]alt|[Nn]once|[Pp]roof|[Tt]oken|Imei|IMEI|Imsi|IMSI|Iccid|ICCID|"
- r"Msisdn|MSISDN|SerialNumber|[Ss]erial)\w*)>[^<]*</\1>"
- )
- XML_IDENT = re.compile(r"<(\w*(?:Ssid|SSID|Mac|MAC|HostName|Hostname|PhoneNumber|WanIPAddress|WanIPv6Address)\w*)>[^<]*</\1>")
- HIDDEN = "<hidden>"
- Note: Usual in code (tag names in paths and patterns): Contains a <hidden> block, a common wrapper for instructions hidden in a tool description
- Line 32 on GitHub
- def _is_public_ip(s: str) -> bool:
- try:
- ip = ipaddress.ip_address(s)
- except ValueError:
- return False
- return ip.is_global
- def is_secret_key(k: str) -> bool:
- k = str(k)
- return bool(SECRET_KEY.search(k)) and not SAFE_KEY.search(k)
- def mask(obj: Any, identifiers: bool = False) -> Any:
- """Return a copy of obj (dict/list/str/number) with secrets (and optionally identifiers) hidden."""
- if isinstance(obj, dict):
- out = {}
- for k, v in obj.items():
- if is_secret_key(k) and v not in ("", None, [], {}) and not isinstance(v, (dict, list)):
- out[k] = HIDDEN
- elif identifiers and IDENT_KEY.search(str(k)) and isinstance(v, str) and v:
- out[k] = _ident(v)
- else:
- out[k] = mask(v, identifiers)
- return out
- if isinstance(obj, list):
- return [mask(v, identifiers) for v in obj]
- if isinstance(obj, str):
- return mask_text(obj, identifiers)
- return obj
- def _ident(v: str) -> str:
- if MAC.fullmatch(v.strip()):
- return "xx:xx:xx:xx:xx:xx"
- return "<redacted>"
- def mask_text(s: str, identifiers: bool = False) -> str:
- s = XML_SECRET.sub(lambda m: f"<{m.group(1)}>{HIDDEN}</{m.group(1)}>", s)
- s = IMEI_LIKE.sub("<id>", s)
- if identifiers:
- s = XML_IDENT.sub(lambda m: f"<{m.group(1)}><redacted></{m.group(1)}>", s)
- s = MAC.sub("xx:xx:xx:xx:xx:xx", s)
- s = re.sub(r"\b\d{1,3}(?:\.\d{1,3}){3}\b", lambda m: "<public-ip>" if _is_public_ip(m.group(0)) else m.group(0), s)
- return s
- def scrub_known(s: str, secrets: list) -> str:
- """Last line of defence: remove any literal secret values we know about from text output."""
- for sec in secrets:
- if sec and len(sec) >= 4:
- s = s.replace(sec, HIDDEN)
- return s
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.