mac-performance-triage
Skill0 starsChanged 18 days agoMITView on GitHub
Use when a Mac is slow, freezing, beachballing, lagging, running hot, or spinning the rainbow wheel; when apps quit or get killed unexpectedly; when the fans are loud or kernel_task is high; when someone asks to "clean up", "speed up", or "free space on" a Mac; or when deciding whether to buy more RAM or a bigger machine. Also use for "why is my laptop so slow", "running out of memory", "out of storage", "should I upgrade my RAM", and post-hoc questions about a freeze that already happened.
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
When RAM runs out, macOS compresses pages rather than swapping.
- Distinctive: line 33
Read-only: kills nothing, deletes nothing, ~5 seconds.
≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Mac Performance Triage
Overview
A slow Mac is almost always a memory-capacity problem wearing a CPU costume.
When RAM runs out, macOS compresses pages rather than swapping. Compression is
fast, but every decompression is a CPU stall. Millions of them read as "the
laptop is slow" and to top as high CPU — while free memory looks fine and the
disk has hundreds of GB free.
Measure the true working set against physical RAM. Everything else is downstream of that number.
Run This First
python3 scripts/mac_triage.py # add --json for machine-readableRead-only: kills nothing, deletes nothing, ~5 seconds.
The Core Calculation
macOS never reports true demand directly. Recover it by inverting the
compressor's own ratio (vm_stat):
ratio = "Pages stored in compressor" / "Pages occupied by compressor"
working_set = (PhysMem_used - compressor_physical) + (compressor_physical × ratio)A ratio near 2:1 is typical. If working_set exceeds installed RAM, the
machine is genuinely oversubscribed and no amount of tidying will fix it.
Signals That Lie
| Signal | Why it misleads |
memory_pressure "free percentage" | Reported 70% free on a machine with 117 MB actually free. Ignore it. |
| Activity Monitor pressure graph | Lags badly; stays green through active thrash. |
ps %cpu | A decaying lifetime average. A process that just started spinning ranks low. Use top -l 2 and read the second sample. |
| Summed RSS per app | Double-counts memory shared between helper processes. Upper bound only. |
Empty /System/Volumes/VM/ | Normal on Apple Silicon — it prefers compression and creates swap lazily. Not a missing safety net, nothing to fix. |
| Free disk space | Irrelevant to speed above ~10% free. |
Hard Evidence of Memory Exhaustion
JetsamEvent-*.ips in ~/Library/Logs/DiagnosticReports means the kernel
already killed processes to reclaim RAM — conclusive. shutdown_stall-*.ips
and lifetime decompressions in the millions corroborate.
Verdict Table
| Working set vs RAM | Verdict |
| Under, but free < 1 GB and decompressions in the millions | Reboot — thrash accumulated over uptime. |
| Over by < 25% | Fixable in software: quit idle Electron apps, enable Chrome Memory Saver, close unused agent sessions. |
| Over by > 25%, persisting after the above | Genuinely undersized; recommend more RAM. |
Apple Silicon RAM is soldered, so this is a purchase decision. Report the chip
tier (machdep.cpu.brand_string — a bare Apple M4 is base tier and caps
lower than Pro/Max) and have the user confirm ceilings with Apple first.
Safety Rules
- Never kill by PID. PIDs are recycled; a stale PID may belong to
something else by the time it's used. Match by name (
pkill -f <pattern>) after previewing withpgrep -fl. - Check capture state before suggesting quits. An active mic tap plus
busy
cameracapturedmeans a live call — quitting apps cuts them off. The script flags this. - Don't run
log showover long windows. A--last 24hquery drove load average from 8 to 21 on a machine already thrashing. Diagnostics must not worsen the problem; readDiagnosticReportsfiles instead. - Never delete user files to fix speed. See below.
Common Mistakes
| Mistake | Correction |
| Treating it as a disk problem | "Slow laptop" and "clean up my Mac" arrive together but are unrelated above ~10% free. Report free space as evidence before anyone deletes. |
| Deleting files to "free things up" | Returns zero performance, and Documents holds originals indistinguishable from drafts by size or mtime. Inventory, let the user decide, never sweep-delete. |
| Quitting apps mid-task | 1 GB isn't worth a dropped call or lost session. Prefer Chrome's Memory Saver and its Task Manager (⇧⌥Esc) over quitting the browser. |
| Chasing a 200 MB orphan | Order recommendations by GB. A leaked helper is satisfying to find and irrelevant next to a 5 GB browser. |
Reference
references/macos-memory-internals.md — compressor mechanics, jetsam bands,
Apple Silicon swap semantics, and the full command inventory.
In this repository31 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- chief-of-staffSkill
- codex-reviewSkill
- conference-prepSkill
- doc-conversion-qaSkill
- eligibility-checkSkill
- fact-checkSkill
- google-adsSkill
- icp-researchSkill
- linkedin-carousel-builderSkill
- meeting-followupSkill
- meeting-prepSkill
- mobile-auditSkill
- one-pager-builderSkill
- ops-metricsSkill
- pmf-pulseSkill
- post-conference-fupSkill
- post-conference-insightsSkill
- postmortemSkill
- prior-auth-review-skillSkill
- product-insightsSkill
- seoSkill
- site-reviewSkill
- solum-health-brandSkill
- task-triageSkill
- team-feedbackSkill
- uscis-petition-reviewSkill
- weekly-retroSkill
- weekly-reviewSkill
- win-lossSkill
- x-healthcare-postsSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.