| name | macos-performance-triage |
| description | Live macOS/Apple-Silicon performance triage — find what's heating the Mac (hot WindowServer, GPU compositing, a CPU-heavy browser/Electron app) and attribute it to the driving process. Use when fans spin up, the Mac is hot/slow, or WindowServer/an app shows high CPU/GPU. |
| user-invocable | false |
| allowed-tools | Bash(uname *), Bash(ps *), Bash(top *), Bash(pgrep *), Bash(uptime *), Bash(vm_stat*), Bash(sysctl *), Bash(macmon *), Bash(btm *), Bash(sample *), Bash(spindump *), Bash(sudo powermetrics *), Bash(samply *), Bash(hyperfine *), Bash(brew install *), Bash(brew list *), Read, Grep, Glob |
| created | "2026-06-30T00:00:00.000Z" |
| modified | "2026-06-30T00:00:00.000Z" |
| reviewed | "2026-06-30T00:00:00.000Z" |
macOS Performance Triage (Apple Silicon)
When to Use This Skill
| Use this skill when... | Use something else when... |
|---|
| The Mac is hot/loud/slow and you need to find what's driving it | The machine actually hung or panicked — use macos-incident-postmortem |
WindowServer shows high CPU/GPU and you need to attribute it to a client app | A security extension (Kandji ESF, XProtect, an EDR) is the hot process — use endpoint-security-cpu |
| One ordinary app (Chrome/Electron, a renderer, a game) is pegging CPU or GPU | launchservicesd is the hot process — use launchservices-health |
| You want a flame graph / deep profile of a specific process | A disk reads near-full or you're reclaiming space — use macos-disk-usage |
| You want a repeatable "what's hot right now" snapshot | syspolicyd/trustd/tccd/auditd are all elevated together (exec storm) — use endpoint-security-cpu |
| You need to attribute a live thermal/CPU/GPU load right now | You want a repeatable baseline scored PASS/WARN/FAIL against thresholds — use macos-performance-benchmark |
Platform Guard
macOS-only. powermetrics, sample, spindump, Instruments, and the
Apple-Silicon power counters macmon reads are Darwin-specific.
test "$(uname -s)" = "Darwin" || { echo "macos-plugin: not Darwin, refusing"; exit 1; }
Core Insight: triage with the USE method; WindowServer is always downstream
Two ideas drive the whole flow:
- USE method (Brendan Gregg) — for each resource ask Utilization,
Saturation, Errors. A bare
ps-by-CPU only answers Utilization.
Saturation (run-queue depth, thermal throttle) and Errors (log stream)
complete the picture. The method is OS-agnostic; only the tools change.
WindowServer never starts its own work. Every cycle it burns was
requested by a client app's draw / animation / compositing. Apps build their
UI as CALayer hierarchies, hand them to WindowServer via IOSurface, and
WindowServer composites (positioning, clipping, masks, shadows, effects) synced
to the display refresh. So a hot WindowServer is a symptom — the job is to
find the app feeding it (continuous video, GIF/Lottie animation, a software /
non-GPU-accelerated render path, layout thrashing).
The deepest tier of Gregg's Linux approach does not transfer: there is no
eBPF / bpftrace on macOS. DTrace is the analogue but SIP blocks it from
tracing Apple-signed/system processes (including WindowServer) unless SIP is
disabled — not worth it for desktop triage. The flow below stays within a
normally-secured Mac.
Step 1 — Quick triage: what's hot
Start with a process snapshot, sorted by CPU. -c shows the short command name:
ps -Aceo pid,pcpu,pmem,comm -r | head -16
Then get the Apple-Silicon power/thermal picture. macmon (Rust) is the
preferred tool — it reads the same data as powermetrics (per-cluster P/E-core
load + frequency, GPU, ANE, package power, temps) but without sudo, via a
private IOReport API. One-shot, scriptable snapshot:
macmon pipe -s 1 | jq -c '{cpu_W:.cpu_power, gpu_W:.gpu_power, ane_W:.ane_power, ecpu_usage, pcpu_usage, gpu_usage, temp}'
Live TUI: macmon. Process/thread breakdown TUI: btm (bottom, Rust).
If the tools are missing, offer to install (all Rust, all sudo-free):
brew install macmon bottom samply hyperfine
Read the snapshot:
- A high non-system process at the top → go to Step 3 (profile it) or just
identify/close it.
WindowServer high → Step 2 (attribute it).kernel_task high → thermal management throttling a real load; find that load.- The whole security stack hot together → this is an exec storm, hand off to
endpoint-security-cpu.
Common phantom offenders
OrbStack Helper — quitting the OrbStack app does not stop the VM; the
helper reparents to launchd (PPID 1) and keeps eating ~40–50% CPU / ~20% RAM
with no visible app. Confirm with ps -Ao pid,ppid,comm | grep -i '[o]rb' (a
PPID of 1 is the tell) and stop it with orb stop, not kill. (Disk side of
the same tool: macos-disk-usage.)- A backgrounded Electron app (Slack, Discord, VS Code) animating off-screen.
- A browser tab running video/WebRTC/canvas — see Step 2.
Step 2 — Attribute WindowServer / GPU load to the driving app
There is no single first-party "blame" button; attribute in layers, cheapest
first:
- Per-process GPU cost (the real lever):
sudo powermetrics --samplers tasks --show-process-gpu -n 1 -i 1000
The app with high GPU here is what's loading WindowServer's compositor.
- Activity Monitor → add the GPU column, sort descending; the Window Spy
picker maps a visible window back to its owning process.
- Instruments → Core Animation template — layer counts, dropped frames,
compositing time (developer-side, if you own the app).
- Instruments → Metal System Trace — catches software-fallback (non-GPU)
render paths and frame-pacing anomalies.
- Quartz Debug (Xcode Additional Tools) — live "flash dirty regions /
overdraw"; visually shows which surfaces re-composite every frame.
Pattern to expect: N live video/WebRTC streams (e.g. a multi-cam call inside a
browser/VTT) = N continuously-invalidating Core Animation layers → per-frame
recomposition. That is a genuine workload floor, not a fault — confirmed when
WindowServer stays hot after you close other GPU consumers.
sample WindowServer 5 and spindump can sample WindowServer itself, but they
show its internal compositing stacks, not which client drove the work — use
powermetrics --show-process-gpu for attribution, not sample.
Step 3 — Deep profiling: flame graph a specific process
For a CPU-heavy process you own, samply (Rust) is the modern path — samples
via Apple's Mach interface (on- and off-CPU), opens in the Firefox Profiler UI
(flame graph + timeline + call tree), no sudo, no SIP changes for your own
binaries:
samply record ./my-program
samply record --pid 12345
- Instruments is more capable (adds GPU, ANE, Metal, PMC counters) but the UI
and
xctrace CLI are sluggish, and attaching to other apps needs entitlements.
cargo flamegraph / FlameGraph + dtrace works for your own code, but SIP
makes dtrace-based graphs low-fidelity for anything system-touching, and can't
graph WindowServer at all without disabling SIP.- A Chrome/Electron renderer is sandboxed —
samply can't see in usefully;
use the app's own chrome://tracing / DevTools Performance tab instead.
For A/B comparing two builds or commands (Gregg-style workload characterization),
hyperfine (Rust) gives warmup + statistics:
hyperfine --warmup 3 './old-build args' './new-build args'
Linux → macOS tool map (for transferring Gregg's playbook)
| Linux (Gregg) | macOS-native | Modern add-on |
|---|
top/htop, vmstat | top -o cpu, vm_stat, sysctl | macmon, bottom (Rust) |
perf | sample, spindump, Instruments | samply (Rust) |
bcc / bpftrace / eBPF | dtrace (SIP-limited) | — (no eBPF on macOS) |
ftrace | ktrace / os_signpost + Instruments | — |
turbostat/power | sudo powermetrics | macmon (sudo-free) |
hyperfine | hyperfine | hyperfine (Rust, cross-platform) |
The toolkit (Rust-forward, all sudo-free unless noted)
| Tool | Lang | Measures | sudo/SIP | Tier |
|---|
| macmon | 🦀 Rust | P/E-core, GPU, ANE, power(W), temp, fans, RAM; JSON + Prometheus | none | triage |
bottom (btm) | 🦀 Rust | procs, CPU, mem, net, disk, temp | none | triage |
powermetrics | C (Apple) | per-process GPU/CPU/ANE, power | sudo | attribution |
| samply | 🦀 Rust | sampling profiler → Firefox Profiler | none (own procs) | profiling |
| hyperfine | 🦀 Rust | CLI benchmark, A/B, stats | none | benchmarking |
| Instruments | Apple | GPU/Metal/ANE/Core Animation/PMC | entitlements | deep |
sample/spindump | Apple | user-stack call-graph | sudo for system procs | profiling |
macmon, bottom, samply, hyperfine install with one line:
brew install macmon bottom samply hyperfine. asitop/mactop are older
equivalents that require sudo; macmon supersedes them.
Output
Report: the hot process(es) with CPU/GPU/power figures; for a hot WindowServer,
the attributed client app and why (animation/video/software-render); the
recommended action (close/stop the driver, lower its settings, or profile it); and
which tier of tool produced the verdict. Distinguish a genuine workload floor (a
live video call) from a fixable runaway (an orphaned VM, a stuck animation).
Related
macos-performance-benchmark — the proactive baseline companion: run a
repeatable, threshold-scored benchmark + diagnostic suite (macmon-first, same
toolkit) to establish what "normal" is before triaging a deviation from it.
