Skip to content

pivoshenko/pivoshenko.ai / skills/macos-maintenance

macos-maintenance

Verified

Periodic macOS maintenance + optimization - read-only health sweep (pending OS/brew updates, disk health + SMART, memory pressure + swap, battery condition, Time Machine recency, Spotlight indexing state, crash/panic reports, uptime, login-item load) -> ok/attention/action report -> confirmed fixes. Use when the user says "maintain my mac", "mac health check", "tune up my mac", "optimize my mac", "run maintenance", "is my mac healthy", "update everything", "my mac is slow / hot / fan is loud", or wants a periodic once-over. Also covers targeted fixes when a check or the user flags an issue - Spotlight reindex, Launch Services rebuild, DNS/font cache flush, frozen Finder/Dock, runaway process triage. Storage/junk/leftovers/disk-space -> macos-cleanup instead.

macOS Maintenance

Periodic once-over: sweep (read-only) -> report -> confirm -> apply -> verify. Optimization = real wins only: updates applied, reboot when due, indexing sane, startup load lean. No snake-oil (purge, blind cache wipes, repair-permissions theater). Storage/junk -> macos-cleanup, hand off.

Sweep (Read-Only)

Run all categories, every one shows up in the report - clean ones as "ok", never silently omitted. Warn up front: softwareupdate -l + diskutil verifyVolume take a minute+.

  1. Updates - softwareupdate -l (slow); brew update >/dev/null && brew outdated (metadata-only refresh, ok in sweep); brew doctor (warnings only, most are noise - flag real ones)
  2. Disk health - df -h / free %; diskutil info disk0 | grep -i smart -> must say Verified; diskutil verifyVolume / (read-only First Aid, live-volume ok); tmutil listlocalsnapshots / count (thinning is automatic - report only)
  3. Memory/CPU - memory_pressure (plain run prints summary); sysctl vm.swapusage - heavy swap + warning level -> note worst consumers via top -l 2 -o mem -n 5 -stats pid,command,cpu,mem
  4. Battery - pmset -g batt; system_profiler SPPowerDataType | grep -E 'Cycle Count|Condition|Maximum Capacity' -> Condition ≠ Normal or capacity <80% = attention
  5. Backups - tmutil destinationinfo (configured at all?); tmutil latestbackup (may need Full Disk Access -> fallback tmutil listbackups | tail -1). Last backup >7d = attention; not configured = say so once, user's call
  6. Spotlight - mdutil -s / (enabled? stuck "in progress"?); ps aux | grep -E 'mds_stores|mdworker' | grep -v grep CPU%. Optimization: big dev trees indexed -> suggest Spotlight Privacy exclusions for build-artifact dirs (node_modules, target, .venv parents) - GUI only, System Settings -> Spotlight (Siri & Spotlight on pre-15)
  7. Crashes/panics - ls -lt ~/Library/Logs/DiagnosticReports | head; ls /Library/Logs/DiagnosticReports 2>/dev/null | grep -i panic. Repeated crashes of one app or any kernel panic = attention + name it
  8. Uptime - uptime. >14d -> recommend reboot (memory leaks + pending updates accumulate; that's the whole fix, no theater)
  9. Startup load - osascript -e 'tell app "System Events" to get name of every login item' + LaunchAgents count. Just the headcount here - deep dead-agent audit lives in macos-cleanup, point there if list looks bloated

Report

Table per category: check · finding · verdict (ok / attention = watch it / action = fix available, named). Lead with one-line summary: "N ok, N attention, N actions available". Then AskUserQuestion multiSelect over the actions only.

Actions (Each Confirmed, Side Effects Stated First)

  • OS updates: sudo softwareupdate -i -a - sudo -> ask; may require restart, say which updates do
  • brew upgrade: brew upgrade - list what bumps first; pinned/work-critical tools -> per-formula brew upgrade <f> instead
  • Reboot: recommend, user does it themselves
  • Spotlight reindex (stuck/corrupt index): sudo mdutil -E / - search degraded for hours on big disks, mds burns CPU meanwhile. One bad folder -> cheaper: add to Spotlight Privacy, wait 1 min, remove -> reindexes just it, no sudo
  • First Aid repair (verify found errors): live / can't be repaired mounted -> Recovery Mode First Aid, give steps; data risk = back up first

Targeted Fixes

When sweep or user flags a specific breakage. Same contract: confirm first, side effects stated, verify after.

  • "Open With" duplicates - /System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -kill -r -domain local -domain system -domain user && killall Finder. Resets custom default handlers to Apple defaults - user re-assigns by hand. No sudo. Verify: dupes gone
  • DNS stale/failing - diagnose first: ping -c 3 8.8.8.8 vs ping -c 3 google.com (IP ok + name fails = DNS; both fail = network, out of scope); scutil --dns | head -30 for stale VPN resolvers (flush won't fix those - point at VPN client). Fix: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder. Instant, no side effects
  • Garbled fonts (across apps; one app -> app problem) - ls -lt ~/Library/Fonts | head, recently added font often culprit, remove it first. Else atsutil databases -removeUser && atsutil server -shutdown && atsutil server -ping (no sudo); still broken -> sudo atsutil databases -remove. Needs relogin to fully take
  • Frozen UI - Finder: killall Finder; Dock: killall Dock; menu bar: killall SystemUIServer - all auto-relaunch, no data loss. No audio: sudo killall coreaudiod (~2s). Never killall WindowServer - force-logout, unsaved work dies; prefer reboot
  • Runaway process (hot/loud/draining) - top -l 2 -o cpu -n 10 -stats pid,command,cpu,mem (second sample is the real one); ps -Ao pid,pcpu,pmem,etime,comm -r | head -15; battery angle: sudo powermetrics -n 1 --samplers tasks | head -40 (fails on some setups -> top is fine). Identify owner before kill: known daemon (mds* -> Spotlight above; bird/fileproviderd = iCloud sync, out of scope, say so) / user app (unsaved work - confirm saved) / helper (respawns, safe). Kill: kill <pid> -> 5s -> kill -9 <pid>; root-owned -> sudo kill, ask. Respawns + spins again -> whack-a-mole, find the cause instead

Rules

  • Sweep = read-only (brew metadata refresh is the one allowed mutate). Change state only via confirmed actions, one at a time -> verify -> next
  • No sudo by default - sudo command -> quote it, say why, ask
  • Side effects before confirm, always: restart-required updates, hours-long reindex, handler resets, relogin
  • No snake-oil: no purge, no "free RAM", no scheduled blind cache wipes, no repair theater. A clean sweep -> "all healthy", stop - don't invent actions
  • User may want the report only - fixing is optional, never assumed
  • Never report a finding this file predicts - the verdict comes from the run, not from here. Baked-in findings are how an audit skill rots
  • Boundaries: disk space/junk/leftovers/dead launch agents -> macos-cleanup; iCloud sync internals, Time Machine repair beyond status, Bluetooth -> out of scope, name it instead of improvising
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall