Net Detective

Run structured network diagnostics and explain findings in plain English.

Scripts

• - scripts/diagnose.py — orchestrates all tests, outputs unified JSON
• INLINECODE1 — tests DNS resolution across Google, Cloudflare, and system resolvers
• INLINECODE2 — measures download throughput via curl (no external packages)
• INLINECODE3 — records results over time, detects anomalies vs baseline
• INLINECODE4 — converts diagnostic JSON into a plain-English markdown report

All scripts use Python stdlib only. Cross-platform: macOS and Linux.

Reference references/diagnostic-guide.md for what each test measures and common failure patterns.

Standard Workflow

1. Run the full diagnostic

CODEBLOCK0

Add --speed to include a bandwidth test (adds ~20s):
CODEBLOCK1

Skip traceroute or MTU if time-constrained:
CODEBLOCK2

2. Compare against history (if available)

CODEBLOCK3

If no history exists yet, skip this step.

3. Generate the report

Without history:
CODEBLOCK4

With history comparison:
CODEBLOCK5

4. Record result to history

CODEBLOCK6

Do this after every diagnostic run to build a baseline over time.

Flags Reference

Interpreting Results

• - DNS failures/slowness — websites appear down even when servers are up; most common cause of "internet is broken" when pings still work
• Packet loss at early hops (1–3) — local network issue (router, cable, Wi-Fi)
• Packet loss at hops 3–6 — ISP problem, outside your control
• High latency, no loss — congestion, either local or upstream
• MTU < 1472 — fragmentation; common with VPNs or PPPoE connections
• Speed drop but latency fine — possible ISP throttling

Read references/diagnostic-guide.md for full pattern descriptions and remediation steps.

Presenting Findings to the User

• - Lead with the headline finding, not raw numbers
• Reference baseline comparisons when available ("This is 3x slower than your normal")
• Give actionable next steps, not just observations
• If the issue is outside the user's control (ISP), say so clearly