macos-cleaner

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. Precision Deletion Only: Delete by specifying exact object IDs/names. Never use batch prune commands.
3. Every Object Listed: Reports must show every specific image, volume, container — not just "12 GB of unused images".
4. 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.
5. 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.
6. Impact Analysis Required: Every cleanup recommendation MUST include "what happens if deleted" column. Never just list items without explaining consequences.
7. Double-Check Before Delete: Verify each Docker object with independent cross-checks before deletion (see references/docker_analysis.md).
8. Patience Over Speed: Disk scans can take 5-10 minutes. NEVER interrupt or skip slow operations. Report progress to user regularly.
9. User Executes Cleanup: After analysis, provide the cleanup command for the user to run themselves. Do NOT auto-execute cleanup.
10. Conservative Defaults: When in doubt, don't delete. Err on the side of caution.

ABSOLUTE PROHIBITIONS:

• ❌ NEVER use docker image prune, docker volume prune, docker system prune, or ANY prune-family command (exception: docker builder prune is safe — build cache contains only intermediate layers, never user data)
• ❌ NEVER use docker container prune — stopped containers may be restarted at any time
• ❌ NEVER run rm -rf on user directories without explicit confirmation
• ❌ NEVER run mo clean without --dry-run preview first
• ❌ NEVER skip analysis steps to save time
• ❌ NEVER append --help to Mole commands (only mo --help is safe)
• ❌ NEVER present cleanup reports with only categories — every object must be individually listed
• ❌ 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.

Command	Purpose	Use When
mo analyze	Interactive disk usage explorer (TUI tree view)	PRIMARY: Understanding what's consuming space
mo clean --dry-run	Preview cleanup categories	SECONDARY: Only after mo analyze to see cleanup preview

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 structured results:

📊 Disk Space Analysis (via Mole)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Free space: 27 GB

🧹 Recoverable Space (dry-run preview):

➤ User Essentials
  • User app cache:     16.67 GB
  • User app logs:      102.3 MB
  • Trash:              642.9 MB

➤ Browser Caches
  • Chrome cache:       1.90 GB
  • Safari cache:       4 KB

➤ Developer Tools
  • uv cache:           9.96 GB
  • npm cache:          (detected)
  • Docker cache:       (detected)
  • Homebrew cache:     (detected)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total recoverable: ~30 GB

⚠️ This was a dry-run preview. No files were deleted.

Step 2: Deep Analysis Categories

Scan the following categories systematically. Reference references/cleanup_targets.md for detailed explanations.

Category 1: System & Application Caches

Locations to analyze:

• ~/Library/Caches/* - User application caches
• /Library/Caches/* - System-wide caches (requires sudo)
• ~/Library/Logs/* - Application logs
• /var/log/* - System logs (requires sudo)

Analysis script:

scripts/analyze_caches.py --user-only

Safety level: 🟢 Generally safe to delete (apps regenerate caches)

Exceptions to preserve:

• Browser caches while browser is running
• IDE caches (may slow down next startup)
• Package manager caches (Homebrew, pip, npm)

Category 2: Application Remnants

Locations to analyze:

• ~/Library/Application Support/* - App data
• ~/Library/Preferences/* - Preference files
• ~/Library/Containers/* - Sandboxed app data

Analysis approach:

1. List installed applications in /Applications
2. Cross-reference with ~/Library/Application Support
3. Identify orphaned folders (app uninstalled but data remains)

Analysis script:

scripts/find_app_remnants.py

Safety level: 🟡 Caution required

• ✅ Safe: Folders for clearly uninstalled apps
• ⚠️ Check first: Folders for apps you rarely use
• ❌ Keep: Active application data

Category 3: Large Files & Duplicates

Analysis script:

scripts/analyze_large_files.py --threshold 100MB --path ~

Find duplicates (optional, resource-intensive):

# Use fdupes if installed
if command -v fdupes &> /dev/null; then
  fdupes -r ~/Documents ~/Downloads
fi

Present findings:

📦 Large Files (>100MB):
━━━━━━━━━━━━━━━━━━━━━━━━
1. movie.mp4                    4.2 GB  ~/Downloads
2. dataset.csv                  1.8 GB  ~/Documents/data
3. old_backup.zip               1.5 GB  ~/Desktop
...

🔁 Duplicate Files:
- screenshot.png (3 copies)     15 MB each
- document_v1.docx (2 copies)   8 MB each

Safety level: 🟡 User judgment required

Category 4: Development Environment Cleanup

Targets:

• Docker: images, containers, volumes, build cache
• Homebrew: cache, old versions
• Node.js: node_modules, npm cache
• Python: pip cache, __pycache__, venv
• Git: .git folders in archived projects

Analysis script:

scripts/analyze_dev_env.py

Example findings:

🐳 Docker Resources:
- Unused images:      12 GB
- Stopped containers:  2 GB
- Build cache:         8 GB
- Orphaned volumes:    3 GB
Total potential:      25 GB

📦 Package Managers:
- Homebrew cache:      5 GB
- npm cache:           3 GB
- pip cache:           1 GB
Total potential:       9 GB

🗂️  Old Projects:
- archived-project-2022/.git  500 MB
- old-prototype/.git          300 MB

Cleanup commands (require confirmation):

# Homebrew cleanup (safe)
brew cleanup -s

# npm _npx only (safe - temporary packages)
rm -rf ~/.npm/_npx

# pip cache (use with caution)
pip cache purge

Docker cleanup - SPECIAL HANDLING REQUIRED:

⚠️ NEVER use these commands:

# ❌ DANGEROUS - deletes ALL volumes without confirmation
docker volume prune -f
docker system prune -a --volumes

✅ Correct approach - per-volume confirmation:

# 1. List all volumes
docker volume ls

# 2. Identify which projects each volume belongs to
docker volume inspect <volume_name>

# 3. Ask user to confirm EACH project they want to delete
# Example: "Do you want to delete all volumes for 'ragflow' project?"

# 4. Delete specific volumes only after confirmation
docker volume rm ragflow_mysql_data ragflow_redis_da

---

*Content truncated.*