/maintaining-macos-health

name: maintaining-macos-health
version: 1.4.0
description: Hands-on playbook for macOS disk cleanup, dev-machine optimization, and proactive health alerting. Use when the Mac is full or slow, when a process persistently burns CPU, when a kernel panic / watchdog timeout / vm-compressor-space-shortage / Jetsam event happened, when the user asks to free disk space, audit storage, set up disk/memory/CPU alerts, or restore the same monitoring on a new Mac. Built around Mole (`mo` CLI) for safety guards plus a custom LaunchAgent-based alerter for active warnings. Covers Apple Silicon laptops with heavy AI/Docker workloads. Not for general macOS support, hardware diagnostics, networking issues, GUI / window-manager bugs, Time Machine recovery, or broken app installs.

Maintaining macOS Health

Recovery and prevention playbook for macOS disk and memory crises. Validated against a real watchdog-timeout kernel panic on Apple Silicon caused by `vm_compressor` segments saturated to 100 % with the disk over 90 % full. The same playbook works for routine cleanup or first-time setup on a new machine.

Table of contents

• [When to use](#when-to-use)
• [Skill layout](#skill-layout)
• [Core mental model](#core-mental-model)
• [Standard workflows](#standard-workflows)
• [First interactive use: optional disk responses](#first-interactive-use-optional-disk-responses)
• [A. "Free space NOW" (incident response)](#a-free-space-now-incident-response)
• [B. "Set up alerting" (new machine or first time)](#b-set-up-alerting-new-machine-or-first-time)
• [C. Alerter stopped working / making noise](#c-already-have-alerter-but-it-stopped-working--making-noise)
• [D. "Uninstall an app cleanly"](#d-uninstall-an-app-cleanly)
• [Safety rules (non-negotiable)](#safety-rules-non-negotiable)
• [Domain quirks captured](#domain-quirks-captured)
• [Outcomes scale](#outcomes-scale)

When to use

Trigger on any of:

• Disk free < 20 % or user complains about being out of space
• Watchdog-timeout / kernel panic / "no checkins from watchdogd"
• New `JetsamEvent-*.ips` with `vm-compressor-space-shortage`
• "Mac is slow", swap > 6 GB, sustained Critical memory pressure
• A process persistently consumes a core, or the whole machine stays CPU-saturated
• User wants to set up monitoring/alerting from scratch
• Migration to a new Mac → restore the same alerter
• General "clean my Mac" / "audit storage" / "free space" requests

Skill layout

| File | Use for | |---|---| | `references/triage.md` | First 5 minutes — which signal fired, which tier of cleanup to start with | | `references/cleanup-tiers.md` | Tiered cleanup playbook (10 tiers, zero-risk → discuss-first), copy-paste-safe shell blocks | | `references/never-touch.md` | Categories that **must not** be deleted even under sudo (Mole-derived blacklist + incident-derived additions) | | `references/mole-techniques.md` | What Mole does that we borrow: marker→target map for `mo purge`, safe-path validators, age thresholds | | `references/alerting.md` | Full alerter design: disk/memory/Jetsam critical triggers plus sustained CPU anomaly detection, incident lifecycle, hysteresis, notifier choices, install/restore commands | | `references/optional-disk-responses.md` | First-use offer, installation and operation of two independent opt-ins: emergency Mole cache cleanup below 2%, and a Codex cleanup plan/page at or below 5% with exact-session continuation. | | `assets/mac-health-disk`, `assets/disk_*.py` | Consent-gated disk controller, deterministic inventory, restricted Codex runner and authenticated local selection/confirmation page. Both modes default off. | | `assets/mole-exact-file.sh`, `assets/mole-core-1.39.0.json` | Compatibility-pinned exact-file adapter to Mole; no general `mo clean`, sudo, or shell commands from the agent. | | `assets/space-scan/`, `assets/build-space-scan.sh` | Read-only bulk metadata scanner with explicit directory exclusions and a compact full folder tree; see `references/storage-report.md` for manual inventory | | `assets/render-storage-report.py`, `assets/storage-tree.js` | Append scanner output to the report; lazily expand folders and show largest files | | `assets/mac-health-check` | Production-ready bash script (~250 lines, bash 3.2 compatible) | | `assets/mac-health-action` | Background action dispatcher for read-only Codex/Claude investigations and explicitly confirmed graceful process stopping | | `assets/com.local.mac-health-check.plist` | LaunchAgent plist with `StartCalendarInterval` (StartInterval is broken on laptops) | | `assets/config.sh` | Default config with safe thresholds | | `assets/render-cleanup-plan.py` | Interactive HTML cleanup-plan UI. Renders categorised checkboxes from a JSON of scan findings, serves on `127.0.0.1:18347`, opens browser, waits for the user's selection, writes it to `/tmp/cleanup-selection-<ts>.json`. Used by Workflow A. | | `assets/apply-cleanup-selection.py` | The **only sanctioned way** to apply a cleanup selection. Reads `selected_items` from a selection JSON and executes each item's `command` field. Enforces protected-override check + path validation + Mole-compatible operations log. Prevents drift between what the user picked and what gets deleted. Supports `--dry-run`. |

Read the relevant reference before acting. Do NOT operate from memory of these files — the details are calibrated to a real incident and small changes break safety.

Core mental model

1. **Monitor passively** — Stats menubar (`brew install --cask stats`) — you see issues forming, not just when they explode. 2. **Alert actively, diagnose quietly** — disk, memory, Jetsam, and whole-system CPU saturation are critical. A single process burning CPU is a silent advisory only after a long sustained window; routine samples stay in the log. 3. **Cleanup tiers** — start zero-risk (caches, orphan data), only escalate to project artifacts and sudo categories if needed. Mole's `mo purge` and `mo clean` are the right primary t