mac-system-health
Check a Mac's health from the shell — where the disk space went, what's eating CPU or memory, why it won't sleep (or why it slept during a long job), battery state, Time Machine status and pending upd
SKILL.mdskills/mac-system-health/SKILL.md
GitHubMac system health
Everything here reads. The few commands that change the machine are marked, and none of them should run without the user saying so.
Disk: where did the space go
diskutil info / | grep -E "Container (Total|Free) Space" # the real numbers
df -h /System/Volumes/Data # your files' volume
df -h / lies on modern macOS. / is the sealed, read-only system snapshot; it showed
12 GiB used on a disk that was 76 % full. Your files are on /System/Volumes/Data, and
all APFS volumes share one container, so the container's free space is the only free
space number that matters.
Find the big directories (no ncdu needed):
du -xhd1 ~ 2>/dev/null | sort -h | tail -15
du -xhd1 ~/Library 2>/dev/null | sort -h | tail -10
-xstays on one filesystem;2>/dev/nullhides theOperation not permittedlines from TCC-protected folders (which are then under-counted: grant Full Disk Access to the terminal for a true number, seemac-permissions).duover~/Librarytook ~1.5 minutes on a large home folder. Run it once, save the output, drill down from that.- The usual suspects:
~/Library/Caches,~/Library/Developer(Xcode DerivedData and simulators),~/Library/Messages/Attachments,~/Library/Application Support/<app>, Docker's VM disk,~/Downloads, old iOS backups under~/Library/Application Support/MobileSync/Backup.
Local snapshots and "purgeable" space. Time Machine keeps local APFS snapshots that
hold deleted files' blocks. Finder counts them as purgeable; df counts them as used.
tmutil listlocalsnapshots /
Changes (ask first): tmutil thinlocalsnapshots / 10000000000 4 asks macOS to free up to
10 GB of snapshots; tmutil deletelocalsnapshots <date> deletes one. Deleting caches or
user files is the user's call, item by item. Never rm -rf a Library folder to make room.
CPU and memory
top -l 2 -s 1 -n 10 -o cpu -stats pid,command,cpu,mem | awk '/^PID/{n++} n==2'
ps -Ao pid,%cpu,%mem,rss,comm -r | head -10
memory_pressure | tail -1 # "System-wide memory free percentage: 54%"
sysctl -n vm.swapusage
sysctl -n hw.memsize machdep.cpu.brand_string
top -l 1shows 0.0 % CPU for everything: CPU is a delta and the first sample has nothing to compare to. Take two samples and keep the second (theawkabove).ps %cpuis a decaying average, good for "what's been busy", bad for "right now".vm_statcounts pages; on Apple silicon a page is 16384 bytes, not 4096 (it says so on its first line). Multiply accordingly or just usememory_pressure.- High memory use alone is normal (macOS fills RAM with cache). The signals are low
free percentage from
memory_pressure, swap that keeps growing, and the yellow/red pressure graph in Activity Monitor. WindowServerhigh = many displays/animations;mds/mdworker/corespotlightdhigh = Spotlight indexing after a big file change (it settles);kernel_taskhigh = thermal throttling (it's cooling the CPU down, not using it).
Killing a process is the user's call; name it and its pid. kill <pid>, never -9 first.
Sleep, power, battery
pmset -g batt # % and charging state
pmset -g | grep -E "sleep|displaysleep|lowpowermode"
pmset -g assertions # who is preventing sleep right now, and why
pmset -g log | grep -E "^\S+ \S+ \S+ (Sleep|Wake|DarkWake)\s\s|Display is turned" | tail -20 # sleep/wake history
sleep 1 (sleep prevented by powerd, ...)inpmset -gnames the blocker. TheListed by owning processsection ofassertionsnames the app and its reason.Keep the Mac awake for a long job (this is the fix for "my overnight run froze"):
caffeinate -dims long-running-command args # awake until the command exits caffeinate -i -t 3600 & # or for a fixed timeIt shows up in
pmset -g assertionsascaffeinate command-line tool. A sleeping Mac freezes timers, so a network timeout in a sleeping process never fires; a job that "hung" overnight is usually a job that slept.Closing the lid on battery sleeps regardless of
caffeinate -i; plug in or keep it open.Changing
pmsetsettings needssudo(a human); reading never does.
Time Machine
tmutil destinationinfo # "No destinations configured." = no backups at all
tmutil latestbackup # path of the newest backup (needs the disk mounted)
tmutil status # Running = 1 while a backup is in progress
Failed to mount backup destination from latestbackup means the disk isn't connected,
not that backups are broken.
Updates and uptime
softwareupdate --history | head # what was installed and when
softwareupdate -l # checks Apple's servers; slow; lists pending updates
uptime
sw_vers
Installing updates (softwareupdate -i) restarts things and needs the user. Report what's
pending; don't install.