dennisonbertram/claude-mac-guardian/performance-check

performance-check

Captures a point-in-time performance snapshot on macOS.

When to invoke

Trigger on phrases like: "check performance", "mac is slow", "why is my mac slow", "cpu usage", "memory pressure", "what's slowing me down".

What to check

1. Load averages — sysctl -n vm.loadavg or uptime. Compare 1-minute load to sysctl -n hw.ncpu.

• load / ncpu < 0.7: ok
• 0.7–1.0: info
• 1.0–2.0: warn
• >2.0: critical

2. Memory pressure — vm_stat (pages free / active / inactive / speculative / wired). Compute pressure ratio: (free + inactive) / total.

• >20% free+inactive: ok
• 10–20%: info
• 5–10%: warn
• <5%: critical

Also parse memory_pressure output when available (memory_pressure 2>/dev/null | tail -5).

3. Swap usage — sysctl vm.swapusage. Parse "used = X.XXM".

• used = 0: ok
• used < 512 MB: info
• 512 MB – 2 GB: warn
• > 2 GB: critical

4. Top 10 CPU consumers — top -l 1 -n 10 -o cpu -stats pid,command,cpu,mem. Record rows.

5. Top 10 memory consumers — top -l 1 -n 10 -o mem -stats pid,command,cpu,mem. Record rows.

6. Thermal state — pmset -g therm 2>/dev/null. Non-zero CPU_Speed_Limit = warn with the value.

7. Battery status (laptops only) — pmset -g batt. Parse percentage, AC Power/Battery Power, charging state. Low percentage on battery with no charger: info.

8. Battery health (laptops only) — ioreg -rc AppleSmartBattery 2>/dev/null. Extract CycleCount, MaxCapacity, DesignCapacity, AppleRawMaxCapacity. Compute MaxCapacity/DesignCapacity × 100:

• ≥ 85%: ok
• 75–85%: info
• 60–75%: warn
• < 60%: critical

Skip gracefully on desktops.

9. Power summary — system_profiler SPPowerDataType 2>/dev/null | head -60 in raw.

10. Uptime — uptime. Uptime > 14 days: info "Consider rebooting; uptime N days."

Output contract

Standard envelope. Write to ~/.mac-guardian/data/performance-check-<ISOdate>.json.

Summary example: "Load 1.32 / 10, 18% memory free, swap 0.0 MB, battery health 92%."

Handoff

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

Safety

• Read-only. Do not kill processes. Do not change pmset settings.
• No sudo.