mac-ops

Files (39)

• SKILL.md
• .gitkeep · assets/
• apple-silicon-specifics.md · references/
• launchd-deep-dive.md · references/
• mac-vs-windows-ops.md · references/
• panic-codes.md · references/
• recovery-patterns.md · references/
• remote-diagnostics.md · references/
• startup-mechanisms.md · references/
• storage-events.md · references/
• symptom-guide.md · references/
• tcc-mechanics.md · references/
• worked-examples.md · references/
• common.sh · scripts/_lib/
• panel.sh · scripts/_lib/
• bluetooth-audit.sh · scripts/
• boot-perf.sh · scripts/
• brew-health.sh · scripts/
• disk-health.sh · scripts/
• drive-dependencies.sh · scripts/
• firewall-audit.sh · scripts/
• font-audit.sh · scripts/
• health-audit.sh · scripts/
• kext-audit.sh · scripts/
• keychain-audit.sh · scripts/
• media-libraries.sh · scripts/
• network-locations.sh · scripts/
• panic-triage.sh · scripts/
• quickrun.sh · scripts/
• recover-clone.sh · scripts/
• safe-disable-startup.sh · scripts/
• spotlight-status.sh · scripts/
• startup-audit.sh · scripts/
• storage-pressure.sh · scripts/
• sysdiagnose-helper.sh · scripts/
• tcc-audit.sh · scripts/
• update-state.sh · scripts/
• wake-reasons.sh · scripts/
• run.sh · tests/

SKILL.md (first lines)

# mac-ops

> Verified as of 2026-07 — content assumes macOS 13 (Ventura) and later (`.ips` panic format on macOS 12+, universal SSH on macOS 13+).

## Helps with

Slow Mac, silent drive failure, unexplained panics, TCC denials, a full disk, 3am wakes, runaway system daemons, login loops, safe eject, failing-drive cloning, remote and Apple Silicon diagnostics. Where each signal lives: [references/symptom-guide.md](references/symptom-guide.md).

## The Universal Insight

**macOS tells you what's wrong if you ask the right log in the right way.** Most users (and most tutorials) reach for Activity Monitor or "About This Mac". The actual diagnostic signal lives in `log show` (the unified logging system), in `/Library/Logs/DiagnosticReports/`, in `pmset -g log`, in the TCC databases, and in `launchctl print`. This skill packages the queries that turn noise into a verdict.

The most common diagnostic failure: treating symptoms in isolation. "Slow boot" → disable login items. "Kernel panic" → reinstall macOS. "Random freezes" → reset SMC/NVRAM. These are reasonable last resorts, but the data to identify the *actual* cause is sitting in the unified log untouched. Always audit before treating.

## The Diagnostic Ladder

Walk down the layers in order. Each rung has a binary outcome:

```
1. Hardware health     — pmset, SMC errors, thermal events, Secure Enclave
2. Storage health      — APFS state, IO errors, snapshot bloat
3. Panic record        — DiagnosticReports/*.{panic,ips} + kext provenance
4. Pre-panic timeline  — log show last 10 minutes before each panic
5. Startup inventory   — Login Items + LaunchAgents + LaunchDaemons + profiles
6. Resource pressure   — top CPU/mem, mds_stores, photoanalysisd, cloudd
7. Permissions / TCC   — what app is denied what (the macOS-unique rung)
8. Verdict             — what's failing, what to do
```

The most interesting failures cluster at rungs 2 (storage), 5 (startup bloat), and 7 (TCC denials). The least interesting (but most-treated) is rung 6.

## Workflow

### 1. Run the comprehensive audit

```bash
scripts/health-audit.sh
```

Produces a verdict block: hardware events, storage health per volume, recent panics, top resource consumers, startup inventory, TCC denials. Scan for `[FAIL]` markers — that's where to drill.

### 2. Drill into the failing layer

| Symptom | Script |
|---|---|
| Storage errors flagged | `scripts/disk-health.sh -v /Volumes/X` (or `-d disk2`) — focused per-volume deep dive: APFS state, IO errors, snapshot bloat, verdict |
| Recent panic | `scripts/panic-triage.sh` (latest by default) or `-f /Library/Logs/DiagnosticReports/Kernel_*.panic` — kext + pre-panic timeline |
| "Is it safe to eject volume X?" | `scripts/drive-dependencies.sh -v /Volumes/X` — open files, Spotlight index, TM target, Photos lib, helper-tool bookmarks |
| "Why is boot taking so long?" | `scripts/boot-perf.sh` — per-boot durations from log show, with slow-component flags |
| App can't see screen/mic/files | `scripts/tcc-audit.sh -a <bundle-id-or-name>` — what TCC has granted, what's been denied recently |
| Mac waking at night | `scripts/wake-reasons.sh` — pmset log breakdown by reason class |
| Spotlight broken / mds CPU spike | `scripts/spotlight-status.sh` — index state per volume, common fixes |
| Storage "full" but disk usage doesn't add up | `scripts/storage-pressure.sh` — APFS snapshots, local Time Machine, purgeable bytes |
| Kernel panic blames a kext / loaded kext audit | `scripts/kext-audit.sh` — third-party kexts + system extensions + SIP/security policy state |
| Firewall behavior / VPN tunnel inventory | `scripts/firewall-audit.sh` — ALF + pf + Network Extension content filters + utun inventory |
| Network preferences across location profiles | `scripts/network-locations.sh` — DNS / proxy / search domains per location, service order |

### 3. Apply the minimum reversible fix

| Action | Script |
|---|---|
| Disable startup item by name | `scripts/safe-disable-startup.sh -n <pattern>` — works across Login Items + LaunchAgents (no sudo for user-scope) |
| List current state of all startup entries | `scripts/safe-disable-startup.sh --list` |
| Re-enable previously disabled | `scripts/safe-disable-startup.sh -n <pattern> --enable` |
| Disable system-scope daemon (admin) | `sudo launchctl disable system/<label>` then `sudo launchctl bootout system/<label>` |
| Reset TCC for a specific service+bundle | `tccutil reset <Service> <bundle-id>` (per-service, not global) |
| Safe clone from failing drive | `scripts/recover-clone.sh -s <source> -d <destination>` — rsync `--partial --inplace --no-whole-file` |

All disables are reversible — Login Items via `osascript` System Events, LaunchAgents via `launchctl disable`. The inverse re-enables.

## Storage Health & Failure Detection

The highest-yield audit. Failing drives cause slow boots (kernel waits on probe timeouts), instability (IO retries cascade into kernel hangs), and panics (paging failures kill `WindowServer`). Three independent data sources to cross-reference:

### IO error events

```bash
log show --last 30d --style compact \
    --predicate 'subsystem == "com.apple.iokit" AND (eventMessage CONTAINS "I/O error" OR eventMessage CONTAINS "media error")' \
    2>/dev/null | head -30
```

Healthy drives produce zero of these per month. Dozens = active failure regardless of what "About This Mac → Storage" claims.

### APFS health

```bash
diskutil apfs list
diskutil apfs verifyVolume /        # READ-ONLY — does not write
```

Look for `Verify failed` per-volume, container free-space mismatches, or snapshot trees growing without bound.

### SMART status (via vendor / smartmontools)

macOS's built-in SMART status (`diskutil info /dev/diskN`) reports only `Verified` or `Failing`. For real attributes, install `smartmontools` (`brew install smartmontools`) and use `smartctl -a /dev/diskN`. NVMe drives often return blank — fall back to vendor tools or the per-vendor utilities.

### Disk → volume mapping

```bash
diskutil list
diskutil info disk2s1
```

Cross-reference with `df -h` for mount point.

## Boot Performance & Startup Management

macOS has **four primary startup mechanisms**, each requiring different tooling. System Settings only shows one of them (Login Items). Full inventory in `references/startup-mechanisms.md`.

| Mechanism | Where | How to inspect | How to disable |
|---|---|---|---|
| Login Items | System Settings → General → Login Items | `osascript` System Events | `osascript` (no sudo) |
| User LaunchAgents | `~/Library/LaunchAgents/*.plist` | `launchctl print gui/$UID` | `launchctl disable gui/$UID/<label>` |
| System LaunchAgents (per-user) | `/Library/LaunchAgents/*.plist` | `launchctl print gui/$UID` | `launchctl disable gui/$UID/<label>` (no sudo for current user) |
| System LaunchDaemons | `/Library/LaunchDaemons/*.plist` | `sudo launchctl print system` | `sudo launchctl disable system/<label>` |
| (Legacy) LoginHook | `com.apple.loginwindow` LoginHook key | `sudo defaults read com.apple.loginwindow LoginHook` | `sudo defaults delete com.apple.loginwindow LoginHook` |

### `launchctl disable` vs `bootout`

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods