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. 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 Step 2A).
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

CODEBLOCK0

Step 1: Quick Diagnosis with Mole

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

1.1 Pre-flight Checks

CODEBLOCK1

1.2 Choose Analysis Method

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

Command	Purpose	Use When
INLINECODE14	Interactive disk usage explorer (TUI tree view)	PRIMARY: Understanding what's consuming space
INLINECODE15

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.

CODEBLOCK2

Alternative: Cleanup preview (use AFTER mo analyze)
CODEBLOCK3

1.4 Progress Reporting

Report scan progress to user regularly:

CODEBLOCK4

1.5 Present Final Findings

After scan completes, present structured results:

CODEBLOCK5

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
• INLINECODE20 - System-wide caches (requires sudo)
• INLINECODE21 - Application logs
• INLINECODE22 - System logs (requires sudo)

Analysis script:
CODEBLOCK6

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
• INLINECODE24 - Preference files
• INLINECODE25 - Sandboxed app data

Analysis approach:

1. 1. List installed applications in INLINECODE26
2. Cross-reference with INLINECODE27
3. Identify orphaned folders (app uninstalled but data remains)

Analysis script:
CODEBLOCK7

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:
CODEBLOCK8

Find duplicates (optional, resource-intensive):
CODEBLOCK9

Present findings:
CODEBLOCK10

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:
CODEBLOCK11

Example findings:
CODEBLOCK12

Cleanup commands (require confirmation):
CODEBLOCK13

Docker cleanup - SPECIAL HANDLING REQUIRED:

⚠️ NEVER use these commands:
CODEBLOCK14

✅ Correct approach - per-volume confirmation:
CODEBLOCK15

Safety level: 🟢 Homebrew/npm cleanup, 🔴 Docker volumes require per-project confirmation

Step 2A: Docker Deep Analysis

Use agent team to analyze Docker resources in parallel for comprehensive coverage:

Agent 1 — Images:
CODEBLOCK16

Agent 2 — Containers and Volumes:
CODEBLOCK17

Agent 3 — System Level:
CODEBLOCK18

Version Management Awareness: Identify version-managed images (e.g., Supabase managed by CLI). When newer versions are confirmed running, older versions are safe to remove. Pay attention to Docker Compose naming conventions (dash vs underscore).

Step 2B: OrbStack-Specific Analysis

OrbStack users have additional considerations.

data.img.raw is a Sparse File:
CODEBLOCK19

The logical vs actual size difference is normal. Only actual usage counts.

Post-Cleanup: Reclaim Disk Space: After cleaning Docker objects inside OrbStack, data.img.raw does NOT shrink automatically. Instruct user: Open OrbStack Settings → "Reclaim disk space" to compact the sparse file.

OrbStack Logs: Typically 1-2 MB total (~/Library/OrbStack/log/). Not worth cleaning.

Step 2C: Double-Check Verification Protocol

Before deleting ANY Docker object, perform independent verification.

For Images:
CODEBLOCK20

For Volumes:
CODEBLOCK21

Database Volume Red Flag Rule: If volume name contains mysql, postgres, redis, mongo, or mariadb, MANDATORY content inspection:
CODEBLOCK22

Only delete after user confirms the data is not needed.

Step 3: Integration with Mole

Mole (https://github.com/tw93/Mole) is a command-line interface (CLI) tool for comprehensive macOS cleanup. It provides interactive terminal-based analysis and cleanup for caches, logs, developer tools, and more.

CRITICAL REQUIREMENTS:

1. 1. TTY Environment: Mole requires a TTY for interactive commands. Use tmux when running from Claude Code or scripts.
2. Version Check: Always verify Mole is up-to-date before use.
3. Safe Help Command: Only mo --help is safe. Do NOT append --help to other commands.

Installation check and upgrade:

CODEBLOCK23

Using Mole with tmux (REQUIRED for Claude Code):

CODEBLOCK24

Available commands (from mo --help):

Command	Safety	Description
INLINECODE37	✅ Safe	View all commands (ONLY safe help)
INLINECODE38

✅ Safe | Disk usage explorer (read-only) |
| mo status | ✅ Safe | System health monitor |
| mo clean --dry-run | ✅ Safe | Preview cleanup (no deletion) |
| mo clean | ⚠️ DANGEROUS | Actually deletes files |
| mo purge | ⚠️ DANGEROUS | Remove project artifacts |
| mo uninstall | ⚠️ DANGEROUS | Remove applications |

Reference guide:
See references/mole_integration.md for detailed tmux workflow and troubleshooting.

Multi-Layer Deep Exploration with Mole

CRITICAL: For comprehensive analysis, you MUST perform multi-layer exploration, not just top-level scans. This section documents the proven workflow for navigating Mole's TUI.

Navigation Commands

CODEBLOCK25

Multi-Layer Exploration Workflow

Step 1: Top-level overview
CODEBLOCK26

Step 2: Enter largest directory (Home)
CODEBLOCK27

Step 3: Drill into specific directories
CODEBLOCK28

Step 4: Navigate back and explore another branch
CODEBLOCK29

Step 5: Deep dive into Library
CODEBLOCK30

Recommended Exploration Path

For comprehensive analysis, follow this exploration tree:

CODEBLOCK31

Time Expectations

Directory	Scan Time	Notes
Top-level menu	5-8 seconds	Fast
Home directory

5-10 minutes | Large, be patient | | ~/Library | 3-5 minutes | Many small files | | Subdirectories | 2-30 seconds | Varies by size |

Example Complete Session

CODEBLOCK32

Key Insights from Exploration

After multi-layer exploration, you will discover:

1. 1. What projects are using DerivedData - specific project names
2. Which caches are actually large - uv vs npm vs others
3. Age of files - Mole shows ">3mo", ">7mo", ">1yr" markers
4. Specific volumes and their purposes - Docker project data
5. Downloads that can be cleaned - old dmgs, duplicate files

Anti-Patterns: What NOT to Delete

CRITICAL: The following items are often suggested for cleanup but should NOT be deleted in most cases. They provide significant value that outweighs the space they consume.

Items to KEEP (Anti-Patterns)

Item	Size	Why NOT to Delete	Real Impact of Deletion
Xcode DerivedData	10+ GB	Build cache saves 10-30 min per full rebuild	Next build takes 10-30 minutes longer
npm _cacache

5+ GB | Downloaded packages cached locally | npm install redownloads everything (30min-2hr in China) | | ~/.cache/uv | 10+ GB | Python package cache | Every Python project reinstalls deps from PyPI | | Playwright browsers | 3-4 GB | Browser binaries for automation testing | Redownload 2GB+ each time (30min-1hr) | | iOS DeviceSupport | 2-3 GB | Required for device debugging | Redownload from Apple when connecting device | | Docker stopped containers | <500 MB | May restart anytime with docker start | Lose container state, need to recreate | | ~/.cache/huggingface | varies | AI model cache | Redownload large models (hours) | | ~/.cache/modelscope | varies | AI model cache (China) | Same as above | | JetBrains caches | 1+ GB | IDE indexing and caches | IDE takes 5-10 min to re-index |

Why This Matters

The vanity trap: Showing "Cleaned 50GB!" feels good but:

• - User spends next 2 hours redownloading npm packages
• Next Xcode build takes 30 minutes instead of 30 seconds
• AI project fails because models need redownload

The right mindset: "I found 50GB of caches. Here's why most of them are actually valuable and should be kept..."

What IS Actually Safe to Delete

Item	Why Safe	Impact
Trash	User already deleted these files	None - user's decision
Homebrew old versions

Replaced by newer versions | Rare: can't rollback to old version | | npm _npx | Temporary npx executions | Minor: npx re-downloads on next use | | Orphaned app remnants | App already uninstalled | None - app doesn't exist | | Specific unused Docker volumes | Projects confirmed abandoned | None - if truly abandoned |

Report Format Requirements

Every cleanup report MUST follow this format with impact analysis:

CODEBLOCK33

Docker Report: Required Object-Level Detail

Docker reports MUST list every individual object, not just categories:

CODEBLOCK34

High-Quality Report Template

After multi-layer exploration, present findings using this proven template:

CODEBLOCK35bash

1. 清空废纸篓 (XXX MB)

手动: Finder → 清空废纸篓

2. npm _npx (X.X GB)

rm -rf ~/.npm/_npx

3. Homebrew 旧版本 (XX MB)

brew cleanup --prune=0 CODEBLOCK36

Report Quality Checklist

Before presenting the report, verify:

• - [ ] Every item has "Impact If Deleted" explanation
• [ ] 🟢 items are truly safe (Trash, _npx, old versions)
• [ ] 🟡 items require user decision (age info, usage patterns)
• [ ] 🔴 items explain WHY they should be kept
• [ ] Docker volumes listed by project, not blanket prune
• [ ] Network environment considered (China = slow redownload)
• [ ] No recommendations to delete useful caches just to inflate numbers
• [ ] Clear action items with exact commands

Step 4: Present Recommendations

Format findings into actionable recommendations with risk levels:

CODEBLOCK37

Step 5: Execute with Confirmation

CRITICAL: Never execute deletions without explicit user confirmation.

Interactive confirmation flow:

CODEBLOCK38

For batch operations:

CODEBLOCK39

Step 6: Verify Results

After cleanup, verify the results and report back:

CODEBLOCK40

Report format:

CODEBLOCK41

Bonus: Dockerfile Optimization Discoveries

During image analysis, if you discover oversized images, suggest multi-stage build optimization:

CODEBLOCK42

Key techniques: multi-stage builds, slim/alpine base images, .dockerignore, layer ordering.

⚠️ Safety Guidelines

Always Preserve

Never delete these without explicit user instruction:

• - ~/Documents, ~/Desktop, ~/Pictures content
• Active project directories
• Database files (.db, .sqlite)
• Configuration files for active apps
• SSH keys, credentials, certificates
• Time Machine backups

⚠️ Require Sudo Confirmation

These operations require elevated privileges. Ask user to run commands manually:

• - Clearing /Library/Caches (system-wide)
• Clearing /var/log (system logs)
• Clearing /private/var/folders (system temp)

Example prompt:
CODEBLOCK43

💡 Backup Recommendation

Before executing any cleanup >10GB, recommend:

CODEBLOCK44

Troubleshooting

"Operation not permitted" errors

macOS may block deletion of certain system files due to SIP (System Integrity Protection).

Solution: Don't force it. These protections exist for security.

App crashes after cache deletion

Rare but possible. Solution: Restart the app, it will regenerate necessary caches.

Docker cleanup removes important data

Prevention: Always list Docker volumes before cleanup:
CODEBLOCK45

Resources

scripts/

• - analyze_caches.py - Scan and categorize cache directories
• INLINECODE55 - Detect orphaned application data
• INLINECODE56 - Find large files with smart filtering
• INLINECODE57 - Scan development environment resources
• INLINECODE58 - Interactive deletion with confirmation
• INLINECODE59 - Generate before/after reports

references/

• - cleanup_targets.md - Detailed explanations of each cleanup target
• INLINECODE61 - How to use Mole alongside this skill
• INLINECODE62 - Comprehensive list of what to never delete

Usage Examples

Example 1: Quick Cache Cleanup

User request: "My Mac is running out of space, can you help?"

Workflow:

1. 1. Run quick diagnosis
2. Identify system caches as quick win
3. Present findings: "45 GB in ~/Library/Caches"
4. Explain: "These are safe to delete, apps will regenerate them"
5. Ask confirmation
6. Execute: INLINECODE63
7. Report: "Recovered 45 GB"

Example 2: Development Environment Cleanup

User request: "I'm a developer and my disk is full"

Workflow:

1. 1. Run INLINECODE64
2. Present Docker + npm + Homebrew findings
3. Explain each category
4. Provide cleanup commands with explanations
5. Let user execute (don't auto-execute Docker cleanup)
6. Verify results

Example 3: Finding Large Files

User request: "What's taking up so much space?"

Workflow:

1. 1. Run INLINECODE65
2. Present top 20 large files with context
3. Categorize: videos, datasets, archives, disk images
4. Let user decide what to delete
5. Execute confirmed deletions
6. Suggest archiving to external drive

Best Practices

1. 1. Start Conservative: Begin with obviously safe targets (caches, trash)
2. Explain Everything: Users should understand what they're deleting
3. Show Examples: List 3-5 example files from each category
4. Respect User Pace: Don't rush through confirmations
5. Document Results: Always show before/after space usage
6. Educate: Include maintenance tips in final report
7. Integrate Tools: Suggest Mole for users who prefer GUI

When NOT to Use This Skill

• - User wants automatic/silent cleanup (against safety-first principle)
• User needs Windows/Linux cleanup (macOS-specific skill)
• User has <10% disk usage (no cleanup needed)
• User wants to clean system files requiring SIP disable (security risk)

In these cases, explain limitations and suggest alternatives.