optimize-network

Optimize Network

Use this skill to run a safe, evidence-first network optimization workflow. The default posture is read-only diagnosis, then small reversible experiments, then before/after verification. Never treat VPN, proxy, TUN, or routing tools as junk processes.

Safety Contract

Follow these rules before any command that could affect connectivity:

• Intent lock: the goal is speed, latency, responsiveness, and stability, not cleaning network configuration.
• Proxy/VPN protection: do not stop, restart, unload, delete, reconfigure, or bypass Clash, Mihomo, Shadowrocket, Tailscale, V2Ray, Surge, WireGuard, OpenVPN, corporate VPNs, or their TUN interfaces unless the user explicitly requests that exact operation.
• Default read-only: diagnostics may run directly; changes require a short proposal with risk, rollback, and expected effect.
• Reversible first: prefer temporary A/B tests, service reordering, DNS experiments, cache flushes, and user-confirmed app closure over deletion.
• No silent degradation: if a change breaks access to AI tools, proxy, remote work, DNS, or LAN devices, revert it or report the blocker immediately.
• No destructive cleanup: do not delete network locations, profiles, VPN configs, proxy configs, launch agents, routes, or firewall rules. If deletion looks useful, propose disable/dry-run first.
• Sudo caution: any sudo, interface down/up, DHCP reset, route change, or network service disable must be confirmed by the user first.
• Remote session caution: if the user may be connected through SSH, remote desktop, RustDesk, Tailscale, or VPN, ask before any change that could disconnect them.

Routing Decision

Choose one mode and state it briefly:

• execute_direct: read-only diagnosis, report generation, or a user-approved reversible command.
• plan_first: multi-step optimization, DNS change, service-order change, AWDL/AirDrop test, or anything that may affect connectivity.
• clarify_first: OS is unknown, user is remote over the network, proxy/VPN ownership is unclear, or the requested change would modify VPN/proxy/TUN state.

Use these handoff fields in the report: goal, context, constraints, actions, evidence, decision, rollback, next step.

Evidence Hierarchy

Prefer fresh local measurements over assumptions:

1. System route/proxy/DNS state: scutil --nwi, scutil --dns, scutil --proxy, route -n get default.
2. Link quality: gateway ping, packet loss, Wi-Fi RSSI/noise/Tx Rate/channel, Ethernet state.
3. Responsiveness: macOS networkQuality -v and, when available, speedtest-cli.
4. DNS: repeated dig +tries=1 +time=2 +stats against relevant domains.
5. Process/network load: nettop, lsof, Mihomo read-only connections API when present.
6. Before/after comparison from the same commands, same route/proxy state, and close in time.

Do not claim improvement from a single noisy datapoint. Call out variance when results are mixed.

Workflow

1. Preflight

Identify the operating system and active path:

uname -a
sw_vers 2>/dev/null || true
command -v networkQuality || true
command -v speedtest-cli || true
command -v speedtest || true
scutil --nwi 2>/dev/null || true
scutil --proxy 2>/dev/null || true

If macOS is detected, prefer the bundled read-only snapshot helper:

~/.claude/skills/optimize-network/scripts/macos_network_snapshot.sh

Run the bandwidth/responsiveness portion only when the user is ready for a bandwidth-consuming test:

RUN_NETWORKQUALITY=1 ~/.claude/skills/optimize-network/scripts/macos_network_snapshot.sh

If testing from a local Codex skill copy instead of an installed Spellbook copy, use the equivalent path under ~/.codex/skills/optimize-network/scripts/.

2. Baseline

Record:

• OS, timestamp, active network service/interface, default gateway, route table summary.
• Whether tests are direct or proxied. If system proxy/TUN is active, say that throughput and latency measure the proxy path.
• networkQuality -v or speedtest-cli download/upload/latency.
• Gateway ping and at least one regional public ping.
• DNS servers and dig timing for user-relevant domains.
• Wi-Fi channel, band, RSSI/noise, Tx Rate, and PHY mode when available.
• Active proxy/VPN processes and read-only connection counts if relevant.

3. Diagnose Top Bottlenecks

Limit the finding list to the most likely 3-4 bottlenecks. Common categories:

• Local link jitter: gateway ping spikes, Wi-Fi channel contention, AWDL/AirDrop/Handoff scanning, router CPU/load.
• Bufferbloat: good bandwidth but high loaded latency in networkQuality.
• DNS instability: repeated lookup variance or slow first query for domains the user actually uses.
• Proxy path mismatch: speed tests or AI tools are routed through slow proxy groups or residential nodes.
• Service order drift: unused adapters ahead of the active Wi-Fi/Ethernet service.
• Background traffic: high network throughput from sync, browser, remote desktop, update, or chat apps.
• MTU/path issues: large ping failure with DF set, packet loss to nearby destinations.

Separate confirmed facts from hypotheses.

4. Safe Optimization Menu

Only apply a change after explaining risk and rollback.

DNS A/B test

Use when DNS lookup is repeatedly slow or inconsistent. Save current DNS first:

networksetup -getdnsservers Wi-Fi

Candidate examples for China mainland networks: 223.5.5.5, 119.29.29.29, 114.114.114.114. Test by setting, flushing cache, repeating dig and curl -w, then keep only if it clearly improves results. Roll back with the saved DNS:

networksetup -setdnsservers Wi-Fi <saved-dns...>
dscacheutil -flushcache

Network service order

Use when inactive adapters are above the real interface and route evidence suggests confusion. First show the current order:

networksetup -listnetworkserviceorder

Propose the exact new order. Preserve VPN/proxy services and do not remove them. Apply only after confirmation:

networksetup -ordernetworkservices "<primary>" "<secondary>" "<other-services...>"

Unused service disable

Use only for clearly unused physical/virtual adapters, and prefer disable over delete. Never disable VPN/proxy/TUN services by default. Show:

networksetup -listallnetworkservices

Apply only after confirmation:

networksetup -setnetworkserviceenabled "<service-name>" off

Rollback:

networksetup -setnetworkserviceenabled "<service-name>" on

AWDL/AirDrop A/B test

Use when Wi-Fi signal is strong but gateway ping has periodic spikes. This may affect AirDrop, AirPlay, Handoff, Universal Control, and Apple Watch unlock. It usually requires sudo, so confirm first.

Test window:

sudo ifconfig awdl0 down
ping -c 30 <gateway>
sudo ifconfig awdl0 up

Do not leave awdl0 down unless the user explicitly wants that tradeoff.

mDNS/DNS cache refresh

Use when local name resolution or stale DNS is suspected. dscacheutil -flushcache is low risk. mDNSResponder restart needs confirmation if sudo is required:

dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Background traffic

Report top talkers from nettop or lsof. Do not kill processes. Suggest the user pause sync/download/remote desktop apps or ask for confirmation before closing anything.

Bufferbloat / SQM

If loaded latency is high while bandwidth is adequate, local macOS tweaks are unlikely to fix the root cause. Recommend router-side SQM/CAKE/FQ-CoDel if available, with upload/download shaping at roughly 85-90% of measured stable throughput. Treat this as manual router work unless the user explicitly asks for router configuration.

Proxy path optimization

If Clash/Mihomo is active, inspect read-only state before proposing changes:

curl -s --max-time 2 --unix-socket /tmp/verge/verge-mihomo.sock http://localhost/connections
curl -s --max-time 2 --unix-socket /tmp/verge/verge-mihomo.soc