wifi-debug

wifi-debug

Reports on the active wifi association: SSID, RSSI, channel, noise, Tx rate, BSSID, surrounding networks, and recent disconnect events.

When to invoke

Trigger on phrases like: "debug wifi", "wifi not working", "check wifi", "why is wifi slow", "wifi signal".

Data sources and fallbacks

macOS Sonoma and later deprecate airport. Use a layered approach:

1. wdutil info — authoritative on newer macOS. Non-elevated output is usually redacted but still includes SSID, channel, and RSSI on many systems. Invoke without sudo: wdutil info 2>/dev/null. Do not call sudo.
2. Legacy airport — /System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport -I. If the binary exists and returns output, prefer it for RSSI / noise / Tx rate numbers.
3. networksetup — networksetup -getairportnetwork en0 for SSID, networksetup -getinfo "Wi-Fi" for MAC / IP.

If none yield data, emit severity info, summary "Wi-Fi interface off or unavailable."

What to extract

• SSID (string)
• BSSID (string, may be redacted without location permissions — record as "redacted" then)
• Channel (integer + band, e.g. 36 (5GHz))
• RSSI dBm — integer. Severity mapping:
  • ≥ −60: ok
  • −60 to −70: info
  • −70 to −80: warn
  • < −80: critical
• Noise dBm — integer. warn if > −80.
• Tx rate — Mbps. info if < 72, warn if < 24.
• Security type — ok if WPA2/WPA3, warn if WEP or Open.
• MCS index (if available, raw only).

Surrounding networks

If on a legacy macOS where airport -s works, include a count of discovered networks plus the strongest 10 in raw. On Sonoma+, skip with an info finding "airport -s no longer available."

Recent wifi events

log show --style compact --last 1h --predicate 'subsystem == "com.apple.wifi"' 2>/dev/null | tail -60. Skip gracefully if log is unavailable or produces no output. Do not pipe directly into the user's terminal; store the tail in the raw.log_tail field (truncated to ~4 KB).

Output contract

Standard envelope. Write to ~/.mac-guardian/data/wifi-debug-<ISOdate>.json.

Top-level severity = max of RSSI, noise, Tx rate, security severities. Summary example: "SSID HomeNet5G, RSSI −58 dBm, 867 Mbps (ok)."

Handoff

• On direct invocation: bash ${CLAUDE_PLUGIN_ROOT}/scripts/render-single.sh wifi-debug.
• When invoked by daily-health-report, return JSON path only.

Safety

• Never run sudo wdutil info or similar. Report truthfully when detail is redacted.
• Read-only. Do not join / leave / change networks.