| name | whats-hot |
| description | Investigates macOS resource hogs — CPU, memory, disk I/O, GPU — AND network activity, and explains what is happening. For hotness it captures sample(1), vmmap, fs_usage, powermetrics traces to find hot code paths and root causes. For the network it runs the bundled `netmon` tool to show live upload/download speed, which app/process is using the network, per-connection remote IPs and hostnames, a link speed test, and resumable downloads. Use when the user says "what's hot on my mac", "what's using my CPU", "why is my Mac slow / hot / fans loud", "find the process eating RAM", "profile PID", "why is <app> busy" — and for "network / upload / download speed", "what's using my network", "which app is connecting where", "what IPs am I connected to", "watch my network", "a download is stuck / resume it", or "run a speed test". |
What's Hot (macOS)
Two jobs: (1) find resource hogs and explain why they are hot via traces; (2) show and
query network activity — throughput, connections, downloads — via the netmon tool.
Safety rules — non-negotiable
- Observation is read-only. When investigating or monitoring, never
kill/pkill/
renice/launchctl unload and never touch the processes you observe. Recommend, ask the user.
- Downloads are the one explicit write.
netmon get <url> is a user-initiated action that
writes only the file the user asked for. It never reaches into another app's transfer — the
monitor cannot resume Safari/Chrome/App Store downloads (see docs/adr/0001); it can only observe them.
- No silent sudo.
fs_usage, powermetrics, vmmap of other-user PIDs, and netmon -deep
(packet capture) need root. State the command, state why, wait for OK. If ~/.claude/CLAUDE.md
defines a SUDO_ASKPASS protocol, use it.
- One PID per investigation. Multi-PID apps (Chrome, Slack, Electron): list first, pick the hot one.
Which job?
- "why is /my mac hot / slow / fans loud / eating RAM / using CPU / GPU" → Hotness workflow.
- "network / up/down speed, what's using my network, which app connects where, what IPs, watch the
network, a download is stuck, resume a download, speed test" → Network workflow.
Hotness workflow
- Triage —
bash scripts/top-offenders.sh. No sudo.
- Pick PID. Named app →
pgrep -lf <name>, match to step 1.
- CPU profile —
bash scripts/profile-pid.sh <pid> [secs] (default 5). No sudo for own PIDs.
- Hot frames —
bash scripts/summarize-sample.sh <sample-file>.
- Memory —
bash scripts/mem-breakdown.sh <pid>.
- I/O + net (if CPU+mem don't explain) —
bash scripts/io-net-snapshot.sh <pid> [secs]. For
richer per-connection network detail, use netmon snapshot (below).
- GPU (graphical/ML/video only) —
bash scripts/gpu-snapshot.sh [secs]. Sudo.
- Conclude. 3–6 line summary (template below).
Network workflow (netmon)
netmon is a Go tool bundled with this skill. Build it once (needs Go):
bash scripts/build-netmon.sh → installs ~/.local/bin/netmon. The diagnostic scripts above do
not need it; only these network features do.
Drive it by intent — always use snapshot when reporting to the user (the dashboard is for the
human at the browser, not for you):
- "what's using my network / up-down speed / what IPs / which app connects where" →
netmon snapshot -seconds 3 → JSON: machine total up/down bytes-per-sec, per-process throughput,
and per-connection Flows (remote IP, reverse-DNS host, port, protocol, state). Report the top
talkers and their remote endpoints. Add -all to include idle processes; -no-resolve to skip DNS.
- Exact hostname / see plaintext HTTP URLs →
netmon snapshot -deep (adds TLS-SNI hostnames via
packet capture — needs sudo; state the command and wait for OK).
- "pop up a live view / watch my network" → tell the user to run
netmon serve themselves; it
opens a live web dashboard in their browser. Do not run it yourself — you cannot read a live view.
- "a download is stuck / download this and don't let it stall" →
netmon get <url> [-o file].
Auto-resumes on a stall via HTTP range requests. For a stuck download in another app, netmon can
only observe it — tell the user to retry it there.
- "how fast is my connection / run a speed test" →
netmon speedtest (wraps networkQuality; ~15s).
A Remote Endpoint is an IP + hostname + port + protocol, never a full URL — HTTPS encrypts the
path. See docs/CONTEXT.md for the vocabulary and docs/adr/ for the design decisions.
Reporting template (hotness)
PID 1234 — Google Chrome Helper (Renderer)
CPU: 187% Memory: 2.4 GB RSS I/O: idle GPU: n/a
Hot path (62% of samples): blink::Document::updateStyle ← StyleResolver::resolveStyle
Likely cause: heavy CSS recalc, probably in one tab.
Next step: ask the user to identify the tab; suggest closing it.
Trace inconclusive (mostly mach_msg_trap) → say so. No invented cause.
Trace interpretation
See REFERENCE.md: tool catalog, hot-path patterns, CPU vs wait vs I/O.
NOT this skill
- Reproducing perf bugs in your own code →
diagnose skill.
- Fixing an offender → this skill investigates and recommends; it does not kill or restart.
- Persisting network history for later querying → netmon is point-in-time by design (docs/adr/0003).
