Keye Network Optimizer

Use this workflow on macOS. Preserve connectivity, proxy access, VPN access, and remote sessions while collecting comparable evidence.

Non-negotiable safety rules

Follow this order: diagnose, make the smallest reversible change, retest.
Never run destructive resets such as deleting network services, removing VPN profiles, resetting all network preferences, or unloading system daemons.
Do not use sudo, disable a VPN/TUN/proxy, change MTU, or terminate a process without first explaining the effect and obtaining user approval.
Treat a user requirement to keep a proxy for GFW access as a hard constraint.
Record the current value and an exact rollback command before every change.
Do not hardcode interface names, gateway addresses, proxy ports, DNS winners, or network service names from a previous run.
Run throughput, ping, DNS, and traffic sampling sequentially. Concurrent tests create load and invalidate latency and packet-loss comparisons.
Keep before and after conditions identical. A TUN-on versus TUN-off comparison is a separate A/B test and must be labeled as such.

Phase 1: establish scope and safety

Confirm the host is macOS and note whether the user is local or connected through SSH, Screen Sharing, a VPN, or another remote-control path.
Ask whether proxy/VPN/TUN connectivity is mandatory if the user has not said.
Ask other users and applications to pause large transfers for the baseline.
Create a timestamped evidence directory and keep raw before/after outputs.
Do not make changes until all required before measurements are complete.

Use shell variables with task-specific names. If a multi-line snippet uses Bash arrays, run it with bash -lc rather than relying on zsh behavior.

Phase 2: collect the before baseline

Collect these snapshots first:

sw_vers
scutil --nwi
route -n get default
scutil --dns
scutil --proxy
networksetup -listallhardwareports
networksetup -listallnetworkservices
networksetup -listnetworkserviceorder

Derive the active physical interface and gateway from route -n get default. Map that interface to its network service with networksetup -listnetworkserviceorder. Do not assume Wi-Fi is en0 or en1.

Inspect routes for representative destinations:

route -n get 1.1.1.1
route -n get 8.8.8.8
route -n get 100.100.100.100
netstat -rn -f inet
netstat -rn -f inet6

Interpret utun*, 198.18.0.0/15, Tailscale DNS, and split routes as evidence of VPN/TUN involvement. The system default route alone does not prove that a public destination uses the physical interface.

Run the user-experience throughput test once while the machine is idle:

networkQuality

When the system proxy is enabled, normal networkQuality measures the proxy-aware application path. Do not use networkQuality -I <interface> as the raw-link baseline in that state. CFNetwork may still attempt the proxy and fail; that is a measurement conflict, not proof that the network is down. Use route, ping, and interface-bound DNS tests for the raw physical path.

After networkQuality has finished, run idle pings sequentially:

ping -c 30 -i 0.2 <gateway>
ping -c 30 -i 0.2 1.1.1.1
ping -c 30 -i 0.2 8.8.8.8

Record loss, min/average/max, and standard deviation. A public DNS ping may be a TUN-path measurement or may be deprioritized by the destination, so correlate it with route -n get and do not diagnose the WAN from one target alone.

Test DNS servers through the physical interface, bypassing route takeover:

python3 <skill-dir>/scripts/dns_latency.py \
  --interface <physical-interface> \
  --server <current-dns-1> \
  --server <candidate-dns-2> \
  --domain www.apple.com \
  --domain github.com \
  --domain baidu.com \
  --count 3

Include the active DHCP/ISP DNS servers and relevant local candidates. Public resolvers such as 1.1.1.1 or 8.8.8.8 are examples, not automatic winners. Require successful answers across local and international domains. Rank by failures first, then median and p95 latency. Do not select a resolver only from a cached dig result or a single fast response.

Wi-Fi, MTU, cache, and background checks

For Wi-Fi, collect connected channel, band, width, RSSI, noise, Tx Rate, and nearby-channel occupancy:

system_profiler SPAirPortDataType -json

Use the current macOS-supported data source. The old airport utility may be missing, and privileged wdutil commands require approval. Strong RSSI does not rule out narrow channel width, low Tx Rate, interference, or bufferbloat.

Inspect interface MTU and test path MTU without changing it:

ifconfig <physical-interface>
ping -D -s 1472 -c 3 <gateway>
ping -D -s 1400 -c 3 1.1.1.1

Treat ICMP filtering separately from fragmentation. Change MTU only after repeatable evidence and explicit approval because VPN/TUN traffic may break.

Inspect caches and resolver state:

dscacheutil -statistics
scutil --dns

dscacheutil -statistics may not expose cache-node details. That message alone is not a DNS failure.

Inspect route-owning and high-traffic processes with targeted output:

ps -axo pid,ppid,pcpu,pmem,comm,args | rg -i 'tailscale|shadowrocket|stash|surge|clash|mihomo|sing-box|wireguard|openvpn|vpn|cloudflare|warp|zerotier|bird|fileprovider|dropbox|onedrive|google drive|baidunetdisk|netdisk|aria2|transmission|qbittorrent|thunder|xunlei|syncthing|resilio'
nettop -P -L 3 -s 1 -t external -J bytes_in,bytes_out,rx_dupe,rx_ooo,re-tx
lsof -nP -iTCP -sTCP:ESTABLISHED

Use narrow process and connection checks instead of broad binary strings searches. Do not stop sync, download, proxy, or VPN processes automatically. Identify the process and ask the user to pause it when it materially affects the baseline.

Proxy and CLI inheritance checks

When GUI apps work but Terminal or Ghostty CLIs fail, compare all three layers:

scutil --proxy
launchctl getenv HTTP_PROXY
launchctl getenv HTTPS_PROXY
launchctl getenv ALL_PROXY
env | rg -i '^(http_proxy|https_proxy|all_proxy|no_proxy)='

Inspect shell startup files and actual process connections. macOS System Settings proxy values do not automatically become shell environment variables. Before recommending proxy exports, derive the current host and port and verify the candidate proxy with a real HTTP CONNECT request. Existing terminal tabs and running CLIs keep their old environment and must be restarted after an approved shell change.

Phase 3: choose minimal reversible changes

Make a change only when the before evidence supports it:

Service order: move the active physical Wi-Fi or Ethernet service first while preserving every existing service in the command. Save the original complete order for rollback.
Unused service: disable only a clearly inactive old or pseudo service with networksetup -setnetworkserviceenabled <service> off. Never remove it. Do not disable bridges used by virtual machines, docks, Internet Sharing, or remote access.
DNS: set the active physical service to the fastest reliable measured pair with networksetup -setdnsservers <service> <primary> <secondary>. Save whether the original state was DHCP (Empty) or explicit addresses.
Cache: run dscacheutil -flushcache. killall -HUP mDNSResponder normally needs administrator privileges, so explain the brief name-resolution impact and ask before using sudo.
Background load: ask the user to pause the identified process. Send a signal only after approval and prefer a normal application quit.
VPN/TUN: never change it silently. If the user approves an A/B test, preserve a required system proxy, capture TUN-on and TUN-off routes, and restore the chosen state after comparison.

After each change, immediately verify the setting and retain its rollback command. If verification fails, stop and restore the prior value before trying another approach.

Phase 4: retest under matching conditions

Run the same tests in the same order:

Normal networkQuality under the same proxy/TUN state.
Idle gateway ping.
Idle pings to the same public targets.
Interface-bound DNS test with the same domains, count, and timeout.
Route, resolver, proxy, service-order, and process snapshots.

If a metric changes sharply, check for background traffic and repeat only that measurement once. Do not hide regressions or compare unlike proxy/TUN states.

Required final report

Report:

before versus after downlink, uplink, idle latency, loaded responsiveness, gateway/public loss, and DNS failures/median/p95;
whether each metric represents the proxy-aware application path, the TUN path, or the raw physical path;
the three main issues, ordered by impact and backed by evidence;
every applied change and exact rollback command;
skipped privileged or connection-impacting actions;
unresolved items that require manual work, including router/Wi-Fi changes;
whether TUN-on/TUN-off was tested as a separate A/B comparison.

State that network measurements are variable and avoid claiming a lasting gain from a single throughput sample.