| name | network-optimize |
| description | Use to establish a baseline when a user reports slow internet, unstable latency, packet loss, DNS delays, Wi-Fi or Ethernet issues, poor speedtest results, MTU/path-MTU problems, loaded latency, browser-only or terminal-only slowness, IPv4/IPv6 differences, background bandwidth contention, stale saved networks, mDNS/Bonjour/LLMNR noise, VPN-on networking, proxy/PAC/TUN overlap, or Clash/V2Ray/Xray/Mihomo routing conflicts on macOS, Windows, or Linux. |
Network Optimize
Overview
Establish a read-only baseline before any change. Prefer reversible, minimal changes. Explain each meaningful decision with conclusion, reason, risk, next step, scope, and validation.
Never ask the user to disable their VPN/proxy as a first step — preserve the required access path. Do not optimize from a single speed number.
Workflow
- Classify the symptom: web first-load, bulk download, video call, gaming, SSH, Git/npm/pip/Docker, AI API, LAN/NAS, browser-only, terminal-only, VPN-only, or all traffic.
- Identify OS, active interface, default route, DNS, proxy/PAC, VPN/TUN state, IPv4/IPv6 state, browser path, and available tools.
- Run a read-only baseline: responsiveness and loaded latency, bandwidth, DNS transport and answer quality, packet loss, MTU/path-MTU, Wi-Fi/Ethernet link quality, curl timing, route/path, and active bandwidth consumers.
- Compare paths when relevant:
- required VPN/TUN path vs in-app node/mode/rule variations
- direct or no-proxy only when it does not break required access, or when the user explicitly asks for that comparison
- IPv4 vs IPv6
- browser vs curl/terminal
- idle vs loaded network
- LAN target vs public target
- Classify the bottleneck:
- Access: weak Wi-Fi, crowded channel, low negotiated rate, Ethernet negotiation, AP backhaul, router queueing.
- DNS: slow resolver, poor CDN answer, DoH/split DNS mismatch, VPN DNS hijack conflicts, stale cache.
- Path: packet loss, PMTU/MSS mismatch, ISP/CDN route, VPN exit path, bad node.
- Transport/NIC: TCP retransmits, adapter errors/drops, offload/queue/driver problems.
- Application: browser DoH, HTTP/3/QUIC, proxy extension, certificate/security filter, service TTFB.
- Policy: enterprise VPN, NRPT/per-link DNS, MDM/GPO, firewall/EDR/content filter.
- Apply the smallest safe fixes first.
- Validate with the same measurements and summarize before/after numbers plus rollback.
Platform References
Read only the relevant reference:
| Reference | Topic |
|---|
references/common-baseline.md | Common baseline and safety |
references/macos.md | macOS |
references/windows.md | Windows |
references/linux.md | Linux |
references/browser-app-layer.md | Browser/app layer |
references/dns-doh-splitdns.md | DNS, DoH, and split DNS |
references/pmtu-mtu.md | PMTU and MTU |
references/tcp-nic.md | TCP and NIC diagnosis |
references/router-sqm-bufferbloat.md | Router SQM and bufferbloat |
references/vpn-proxy.md | VPN/proxy overlap |
Use this routing table when the symptom already points to a specific layer:
| Symptom | Read first |
|---|
| Calls, games, SSH, or page loads stall during upload/download | references/router-sqm-bufferbloat.md, references/common-baseline.md |
| HTTP/3/QUIC, voice/video, game UDP, or VPN UDP works poorly while TCP works | references/pmtu-mtu.md, references/browser-app-layer.md, references/vpn-proxy.md |
| Browser is slow but curl/terminal is normal | references/browser-app-layer.md, references/dns-doh-splitdns.md |
| Terminal tools are slow but browser is normal | references/browser-app-layer.md, references/vpn-proxy.md, platform reference |
| Internal or corporate domains fail | references/dns-doh-splitdns.md, references/vpn-proxy.md, platform reference |
| IPv4 and IPv6 differ | references/dns-doh-splitdns.md, references/pmtu-mtu.md, platform reference |
| Ethernet negotiates low speed or adapter errors increase | references/tcp-nic.md, platform reference |
| WSL, Docker, registries, npm, pip, or Git are slow while host browsing is normal | references/vpn-proxy.md, references/dns-doh-splitdns.md, platform reference |
Use scripts as read-only diagnostic helpers:
- macOS:
scripts/macos_network_snapshot.sh
- Windows PowerShell:
scripts/windows_network_snapshot.ps1
- Linux:
scripts/linux_network_snapshot.sh
Scripts collect state only; they do not change DNS, MTU, proxy, routes, VPN, firewall, TCP, or NIC settings.
scripts/macos_network_snapshot.sh runs networkQuality by default, which uses Internet data. Set SKIP_BANDWIDTH=1 to skip that section when data usage, metered links, or active calls matter.
Decision Heuristics
- Treat loaded latency/responsiveness as a first-class metric. If idle latency is normal but latency spikes during upload/download, classify loaded-latency or bufferbloat before changing DNS.
- If DNS query time is fast but TCP, TLS, TTFB, or total HTTP time is high, do not over-optimize DNS.
- If DNS is fast but CDN IP or TTFB is poor, compare A, AAAA, HTTPS/SVCB answers, browser Secure DNS state, and curl
remote_ip across resolvers.
- If IPv4 and IPv6 behave differently, treat it as Happy Eyeballs, dual-stack routing, DNS answer quality, PMTU, VPN/TUN, firewall, or CDN behavior before disabling IPv6 globally.
- If HTTP/3/QUIC, VPN, or UDP-heavy apps fail while TCP works, investigate PMTU/UDP/QUIC behavior before lowering global interface MTU.
- If browser and curl disagree, inspect browser Secure DNS/DoH, HTTP/3/QUIC, extensions, NetLog/HAR, cache, certificate interception, and proxy rules.
- If terminal tools are slow but browser is fast, inspect shell proxy variables, WinHTTP, WSL/Docker DNS, CLI CA certificates, and
NO_PROXY.
- If Wi-Fi RSSI is strong but throughput is low, inspect channel width, band, MCS/NSS, BSSID roaming, AP backhaul, WPA mode, and driver.
- If Ethernet negotiates below expected speed, inspect cable, switch port, duplex, EEE, driver, and error counters.
- If adapter errors/drops increase during tests, prioritize NIC/driver/offload/queue diagnosis over DNS or VPN changes.
- If VPN/TUN is active, preserve the required VPN app and compare safe in-app variations first: node, policy/rule mode, TUN vs system proxy ownership when both remain available, DNS mode, UDP/QUIC setting, and browser path. Do not tell the user to pause or quit the VPN app unless they explicitly ask for a direct-access experiment.
- If system DNS is fully overridden by VPN or browser DoH, changing OS DNS may not affect the observed application.
- If MTR/traceroute shows loss on a single intermediate hop but later hops and the destination are clean, treat it as likely ICMP rate limiting.
- If WSL or Docker is slow while the host is normal, inspect virtualization networking, DNS tunneling, auto proxy, container DNS, registry mirror, and VPN compatibility.
- If a change improves one metric but worsens throughput, loss, or loaded latency, roll it back and keep the evidence.
Safe Change Ladder
Use this order unless evidence points elsewhere:
- Read-only diagnosis: routes, DNS, proxy, VPN, Wi-Fi/Ethernet, IPv4/IPv6, curl timing, adapter stats, path tests.
- Low-risk reversible actions: flush DNS cache, switch to better link/AP, change VPN node/protocol, pause a named bandwidth-heavy task.
- Local configuration with evidence and rollback: per-interface DNS, interface MTU, proxy bypass, Wi-Fi profile priority, low-data/metered setting.
- High-risk system configuration: TCP globals, Windows registry/adapter advanced properties, Linux offload/ring/coalescing, firewall, IPv6 disablement, system services. Do not do this by default.
- Network device configuration: router SQM/CAKE, channel width, WPA mode, firmware, AP backhaul, flow offload. Require user authority over the device.
Safety Rules
Do not recommend these as first-line fixes:
- Disable IPv6 globally.
- Disable firewall or security/EDR tools globally.
- Change TCP global parameters without workload evidence.
- Change NIC offload, ring, coalescing, or power settings without packet/error evidence.
- Replace, pause, or disable VPN/proxy apps or corporate DNS before checking split DNS and safe in-app alternatives.
- Force public DNS on corporate networks.
- Delete Wi-Fi profiles without listing them.
- Enable both router SQM and hardware flow offloading as a universal optimization.
- Interpret one speedtest result as the network baseline.
Common Safe Fixes
- Flush DNS cache.
- Prefer Ethernet, 5 GHz, or 6 GHz over crowded 2.4 GHz.
- Add stable secondary DNS only if system DNS is in use and not overridden by VPN, DoH, or enterprise policy.
- Set interface MTU only when path-MTU evidence supports it; prefer VPN/router MSS or MTU tuning when available.
- Remove only clearly obsolete preferred Wi-Fi networks after naming them.
- Avoid duplicate VPN/TUN/proxy ownership while preserving the path the user needs.
- Recommend VPN node/protocol changes if system, link, DNS, and route baselines are already clean.
Reporting
For each meaningful decision, report:
- Conclusion
- Reason
- Risk
- Next step
- Scope and validation method when changing settings
For before/after work, use this structure:
Baseline:
- Symptom:
- Scope: interface / app / VPN path / IPv4 or IPv6 / direct or proxy
- Key metrics: idle latency, loaded latency or responsiveness, packet loss, DNS answers, remote IP, curl timing, throughput
Action:
- Change:
- Why this is the smallest safe change:
- Risk:
- Rollback:
After:
- Same metrics:
- Improved / unchanged / regressed:
- Residual uncertainty:
- Next step:
Finish with exact rollback commands where possible and call out any metric that was not re-measured.
