macOS Cleaner

Overview

Intelligently analyze macOS disk usage and provide actionable cleanup recommendations to reclaim storage space. This skill follows a safety-first philosophy: analyze thoroughly, present clear findings, and require explicit user confirmation before executing any deletions.

Target users: Users with basic technical knowledge who understand file systems but need guidance on what's safe to delete on macOS.

Core Principles

1. Safety First, Never Bypass: NEVER execute dangerous commands (rm -rf, mo clean, etc.) without explicit user confirmation. No shortcuts, no workarounds.
2. Value Over Vanity: Your goal is NOT to maximize cleaned space. Your goal is to identify what is truly useless vs valuable cache. Clearing 50GB of useful cache just to show a big number is harmful.
3. Network Environment Awareness: Many users (especially in China) have slow/unreliable internet. Re-downloading caches can take hours. A cache that saves 30 minutes of download time is worth keeping.
4. Impact Analysis Required: Every cleanup recommendation MUST include "what happens if deleted" column. Never just list items without explaining consequences.
5. Patience Over Speed: Disk scans can take 5-10 minutes. NEVER interrupt or skip slow operations. Report progress to user regularly.
6. User Executes Cleanup: After analysis, provide the cleanup command for the user to run themselves. Do NOT auto-execute cleanup.
7. Conservative Defaults: When in doubt, don't delete. Err on the side of caution.

ABSOLUTE PROHIBITIONS:

• ❌ NEVER run rm -rf on user directories automatically
• ❌ NEVER run mo clean without dry-run preview first
• ❌ NEVER use docker volume prune -f or docker system prune -a --volumes
• ❌ NEVER skip analysis steps to save time
• ❌ NEVER append --help to Mole commands (except mo --help)
• ❌ NEVER recommend deleting useful caches just to inflate cleanup numbers

Workflow Decision Tree

User reports disk space issues
           ↓
    Quick Diagnosis
           ↓
    ┌──────┴──────┐
    │             │
Immediate    Deep Analysis
 Cleanup      (continue below)
    │             │
    └──────┬──────┘
           ↓
  Present Findings
           ↓
   User Confirms
           ↓
   Execute Cleanup
           ↓
  Verify Results

Step 1: Quick Diagnosis with Mole

Primary tool: Use Mole for disk analysis. It provides comprehensive, categorized results.

1.1 Pre-flight Checks

# Check Mole installation and version
which mo && mo --version

# If not installed
brew install tw93/tap/mole

# Check for updates (Mole updates frequently)
brew info tw93/tap/mole | head -5

# Upgrade if outdated
brew upgrade tw93/tap/mole

1.2 Choose Analysis Method

IMPORTANT: Use mo analyze as the primary analysis tool, NOT mo clean --dry-run.

Why prefer mo analyze:

• Dedicated disk analysis tool with interactive tree navigation
• Allows drilling down into specific directories
• Shows actual disk usage breakdown, not just cleanup categories
• More informative for understanding storage consumption

1.3 Run Analysis via tmux

IMPORTANT: Mole requires TTY. Always use tmux from Claude Code.

CRITICAL TIMING NOTE: Home directory scans are SLOW (5-10 minutes or longer for large directories). Inform user upfront and wait patiently.

# Create tmux session
tmux new-session -d -s mole -x 120 -y 40

# Run disk analysis (PRIMARY tool - interactive TUI)
tmux send-keys -t mole 'mo analyze' Enter

# Wait for scan - BE PATIENT!
# Home directory scanning typically takes 5-10 minutes
# Report progress to user regularly
sleep 60 && tmux capture-pane -t mole -p

# Navigate the TUI with arrow keys
tmux send-keys -t mole Down    # Move to next item
tmux send-keys -t mole Enter   # Expand/select item
tmux send-keys -t mole 'q'     # Quit when done

Alternative: Cleanup preview (use AFTER mo analyze)

# Run dry-run preview (SAFE - no deletion)
tmux send-keys -t mole 'mo clean --dry-run' Enter

# Wait for scan (report progress to user every 30 seconds)
# Be patient! Large directories take 5-10 minutes
sleep 30 && tmux capture-pane -t mole -p

1.4 Progress Reporting

Report scan progress to user regularly:

📊 Disk Analysis in Progress...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏱️ Elapsed: 2 minutes

Current status:
✅ Applications: 49.5 GB (complete)
✅ System Library: 10.3 GB (complete)
⏳ Home: scanning... (this may take 5-10 minutes)
⏳ App Library: pending

I'm waiting patiently for the scan to complete.
Will report again in 30 seconds...

1.5 Present Final Findings

After scan completes, present s

...