Mac Optimize

mac-optimize

Fast triage + fix skill for macOS resource pressure on this workstation. Keep CC responsive, keep parallel agents/worktrees from thrashing swap.

When to run

• Load avg > 4 (Apple Silicon: sustained, not spikes)
• sysctl vm.swapusage shows >70% of swap used
• CC replies feel slow / tools time out
• Before starting a parallel-agents session or >2 worktrees
• Session-start (via hook)

Triage: one-shot diagnose

bash ~/.claude/skills/mac-optimize/diagnose.sh

Boost: one-shot apply (reversible)

bash ~/.claude/skills/mac-optimize/boost.sh          # kills zombies, renices competitors, sets NODE_OPTIONS
bash ~/.claude/skills/mac-optimize/boost.sh --purge  # also runs sudo purge (prompts)

Reports: load avg, swap %, top 10 CPU procs, top 10 RSS procs, zombie claude sessions (>6h old), Node version + NODE_OPTIONS, Spotlight worker count.

Common fixes (ranked by impact)

1. Kill zombie claude processes (biggest quick win)

Stale CC sessions hold 400–700MB each. Find + kill anything older than 6 hours:

ps -axo pid,etime,rss,comm | awk '$4=="claude" && $2 ~ /-/ {print $1, $2, $3}'
# Review output, then:
kill <PID>   # not -9; let it flush

Restart via claude --resume if that terminal tab is still open.

2. Free compressed/purgeable memory

sudo purge   # needs password; reclaims cached/purgeable pages

Use when swap >70%. Takes 2–5s. Safe — only drops reclaimable caches.

3. Tune Node heap for CC

Default V8 old-space is ~4GB. On a 24GB Mac running 2+ CC sessions, cap each:

# Add to ~/.zshrc (or ~/.config/zsh/env.zsh)
export NODE_OPTIONS="--max-old-space-size=6144"

Prevents one CC process from ballooning past 6GB when parsing huge tool outputs.

4. Audit launch agents

ls -1 ~/Library/LaunchAgents
launchctl list | grep -v "^-" | sort -k2 -rn | head -15   # sort by PID (running)

Disable unused ones:

launchctl unload -w ~/Library/LaunchAgents/<plist>

5. Spotlight pruning (CC source dirs)

Developer directories don't need Spotlight indexing — saves mdworker CPU:

sudo mdutil -i off /Volumes/External\ HD/Desenvolvimento
sudo mdutil -E /Volumes/External\ HD/Desenvolvimento   # erase existing index

6. Close known high-idle-CPU offenders

Check diagnose output. Usual suspects on this box:

• Bitwarden (20–30% idle CPU — known Electron bug) — quit when not unlocking
• UTM / Virtualization.framework VM — osascript -e 'tell application "UTM" to quit' then kill <VM-XPC-pid> if orphaned (parent=1). Frees 3–4 GB RAM.
• OpenClaw (no longer used on this machine): launchctl unload -w ~/Library/LaunchAgents/ai.openclaw.*.plist + pkill -f openclaw.
• Spotify / Discord / WhatsApp — quit during heavy CC sessions
• Brave tabs — each renderer ≈ 200–300MB, 49 procs ≈ 6.6GB total on this box.

7. Brave Memory Saver (applied 2026-04-15)

Prefs patched at ~/Library/Application Support/BraveSoftware/Brave-Browser/Default/Preferences:

• performance_tuning.high_efficiency_mode.state = 2 (always on)
• tab_discarding.enabled = true

Requires a Brave restart to take effect. After restart, inactive tabs auto-suspend (~60–80% RAM reclaim on idle tabs without losing session).

To reapply after profile reset: re-run the python snippet in boost.sh or:

python3 -c "import json; p='$HOME/Library/Application Support/BraveSoftware/Brave-Browser/Default/Preferences'; d=json.load(open(p)); d.setdefault('performance_tuning',{}).setdefault('high_efficiency_mode',{})['state']=2; d.setdefault('tab_discarding',{})['enabled']=True; json.dump(d,open(p,'w'),separators=(',',':'))"

Preflight before parallel agents / worktrees

Before dispatch-parallel-agents or spawning >2 worktrees, run diagnose. Abort if:

• Free memory < 1GB AND swap > 85%
• Load avg > 6

First run fix #1 (zombies) + #2 (purge), recheck, then proceed.

Integration

• Session-start hook: ~/.claude/hooks/session-start-mac-check.sh runs diagnose and warns if thresholds breached.
• Codex mirror: ~/.codex/scripts/mac-optimize.sh (symlink or copy of diagnose.sh).

Don't do

• Don't kill -9 claude — it leaves orphaned MCP server processes that eat RAM.
• Don't disable Spotlight system-wide (breaks Raycast, Alfred).
• Don't sudo purge in a tight loop — once per hour max.
• Don't set --max-old-space-size above 8192 on a 24GB Mac with VMs running.