mediar-ai/mac-network-doctor

Mac Network Doctor

Diagnose and fix slow macOS internet by finding hidden bandwidth and resource drains.

Workflow

Run phases sequentially. Present findings after each phase and confirm before making changes.

Phase 1: Diagnose

Run scripts/diagnose.sh from the skill directory:

bash <skill-dir>/scripts/diagnose.sh

Parse the output sections and present a summary table:

| Check | Status | Impact | |-------|--------|--------| | VPNs | Found / None | High — adds latency to all traffic | | iCloud sync | Active / Idle | High — constant upload/download | | Desktop/Docs iCloud | Synced / Local | High — dev projects generate churn | | iCloud node_modules | N found, X MB | Medium — unnecessary sync traffic | | Spotlight indexing | N workers, X% CPU | Medium — triggers iCloud downloads | | Dev dirs unprotected | N missing index | Low-Medium — Spotlight indexes junk | | Software Update | Running / Idle | Low-Medium — can download GBs | | Ping latency | Xms avg, Y% loss | Baseline measurement |

Phase 2: Fix

Ask user which issues to fix. For each, see references/fixes.md.

Fix priority order (highest impact first):

1. VPNs — Disconnect/remove VPN proxies (WARP, etc.) that add latency
2. iCloud Desktop & Documents sync — Disable via System Settings (requires macOS automation MCP). This is the single biggest hidden drain for developers
3. iCloud node_modules — Delete node_modules from ~/Library/Mobile Documents/
4. Spotlight exclusions — Add .metadata_never_index to dev artifact dirs
5. Persistent protection — Add shell wrappers to ~/.zshrc for package managers

Important: Always confirm before destructive actions (deleting files, removing VPNs, changing iCloud settings).

Phase 3: Prevent

After fixes, set up persistent protections:

1. Check if ~/.zshrc already has _spotlight_exclude_node_modules function
2. If not, detect installed package managers (which npm bun pnpm yarn)
3. Append wrappers only for installed package managers
4. Verify by sourcing: source ~/.zshrc

Phase 4: Verify

Run the traffic check again:

nettop -m tcp -J bytes_in,bytes_out -l 1 -t wifi 2>/dev/null | sort -t, -k2 -rn | head -20

Also check:

ps aux | grep -i '[c]loudd\|[b]ird\|[c]loudphoto' | awk '{printf "%s%% CPU  %s\n", $3, $11}'
ping -c 5 8.8.8.8

Present a before/after comparison if baseline was captured.

Key gotchas

• warp-cli status may show "Disconnected" but WARP daemon still runs as root — check ps aux | grep CloudflareWARP
• Desktop & Documents iCloud sync cannot be disabled via CLI — must use System Settings GUI (macOS automation MCP)
• mdutil -d only works on volumes, not directories — use .metadata_never_index files for per-directory exclusion
• System extensions (VPN network extensions) are SIP-protected — removing the parent app or VPN config deactivates them
• AWDL (awdl0) is Apple's peer-to-peer Wi-Fi (AirDrop, Sidecar) — it doesn't use internet bandwidth but can cause radio interference

Resources

• scripts/diagnose.sh — Run to collect all diagnostic data in one pass
• references/fixes.md — Detailed fix commands for each issue type