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.

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_data

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

Step 2A-2C: Docker Deep Analysis

For Docker-heavy systems, follow the detailed per-object analysis and verification protocol (image/container/volume inspection, OrbStack sparse-file handling, and the database-volume red-flag rule) in references/docker_analysis.md. Core rule: verify every Docker object with independent cross-checks before deleting, and never use prune-family commands.

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

# Check if installed and get version
which mo && mo --version

# If not installed
brew install tw93/tap/mole

# Check for updates
brew info tw93/tap/mole | head -5

# Upgrade if needed
brew upgrade tw93/tap/mole

Using Mole with tmux (REQUIRED for Claude Code):

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

# Run analysis (safe, read-only)
tmux send-keys -t mole 'mo analyze' Enter

# Wait for scan (be patient - can take 5-10 minutes for large directories)
sleep 60

# Capture results
tmux capture-pane -t mole -p

# Cleanup when done
tmux kill-session -t mole

Available commands (from `mo --help`):

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

Multi-Layer Deep Exploration with Mole

For comprehensive analysis, perform multi-layer exploration (drilling into Home, Library, .cache, .npm, Downloads, etc.) rather than only top-level scans. The full TUI navigation walkthrough, recommended exploration tree, time expectations, and a complete example session are documented in references/mole_integration.md.

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)

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

Report Format Requirements

Every cleanup report MUST follow this format with impact analysis:

## Disk Analysis Report

### Classification Legend
| Symbol | Meaning |
|--------|---------|
| 🟢 | **Absolutely Safe** - No negative impact, truly unused |
| 🟡 | **Trade-off Required** - Useful cache, deletion has cost |
| 🔴 | **Do Not Delete** - Contains valuable data or actively used |

### Findings

| Item | Size | Classification | What It Is | Impact If Deleted |
|------|------|----------------|------------|-------------------|
| Trash | 643 MB | 🟢 | Files you deleted | None |
| npm _npx | 2.1 GB | 🟢 | Temp npx packages | Minor redownload |
| npm _cacache | 5 GB | 🟡 | Package cache | 30min-2hr redownload |
| DerivedData | 10 GB | 🟡 | Xcode build cache | 10-30min rebuild |
| Docker volumes | 11 GB | 🔴 | Project databases | **DATA LOSS** |

### Recommendation
Only items marked 🟢 are recommended for cleanup.
Items marked 🟡 require your judgment based on usage patterns.
Items marked 🔴 require explicit confirmation per-item.

Docker Report: Required Object-Level Detail

Docker reports must list every individual object (each image, container, and volume), not just categories. See the object-level table templates in references/report_templates.md.

High-Quality Report Template

After multi-layer exploration, present findings using the detailed fill-in-the-blank template in references/report_templates.md.

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:

# macOS Cleanup Recommendations

## Summary
Total space recoverable: ~XX GB
Current usage: XX%

## Recommended Actions

### 🟢 Safe to Execute (Low Risk)
These are safe to delete and will be regenerated as needed:

1. **Empty Trash** (~12 GB)
   - Location: ~/.Trash
   - Command: `rm -rf ~/.Trash/*`

2. **Clear System Caches** (~45 GB)
   - Location: ~/Library/Caches
   - Command: `rm -rf ~/Library/Caches/*`
   - Note: Apps may be slightly slower on next launch

3. **Remove Homebrew Cache** (~5 GB)
   - Command: `brew cleanup -s`

### 🟡 Review Recommended (Medium Risk)
Review these items before deletion:

1. **Large Downloads** (~38 GB)
   - Location: ~/Downloads
   - Action: Manually review and delete unneeded files
   - Files: [list top 10 largest files]

2. **Application Remnants** (~8 GB)
   - Apps: [list detected uninstalled apps]
   - Locations: [list paths]
   - Action: Confirm apps are truly uninstalled before deleting data

### 🔴 Keep Unless Certain (High Risk)
Only delete if you know what you're doing:

1. **Docker Volumes** (~3 GB)
   - May contain important data
   - Review with: `docker volume ls`

2. **Time Machine Local Snapshots** (~XX GB)
   - Automatic backups, will be deleted when space needed
   - Command to check: `tmutil listlocalsnapshots /`

Step 5: Execute with Confirmation

CRITICAL: Never execute deletions without explicit user confirmation.

Interactive confirmation flow:

# Example from scripts/safe_delete.py
def confirm_delete(path: str, size: str, description: str) -> bool:
    """
    Ask user to confirm deletion.

    Args:
        path: File/directory path
        size: Human-readable size
        description: What this file/directory is

    Returns:
        True if user confirms, False otherwise
    """
    print(f"\n🗑️  Confirm Deletion")
    print(f"━━━━━━━━━━━━━━━━━━")
    print(f"Path:        {path}")
    print(f"Size:        {size}")
    print(f"Description: {description}")

    response = input("\nDelete this item? [y/N]: ").strip().lower()
    return response == 'y'

For batch operations:

def batch_confirm(items: list) -> list:
    """
    Show all items, ask for batch confirmation.

    Returns list of items user approved.
    """
    print("\n📋 Items to Delete:")
    print("━━━━━━━━━━━━━━━━━━")
    for i, item in enumerate(items, 1):
        print(f"{i}. {item['path']} ({item['size']})")

    print("\nOptions:")
    print("  'all'    - Delete all items")
    print("  '1,3,5'  - Delete specific items by number")
    print("  'none'   - Cancel")

    response = input("\nYour choice: ").strip().lower()

    if response == 'none':
        return []
    elif response == 'all':
        return items
    else:
        # Parse numbers
        indices = [int(x.strip()) - 1 for x in response.split(',')]
        return [items[i] for i in indices if 0 <= i < len(items)]

Step 6: Verify Results

After cleanup, verify the results and report back:

# Compare before/after
df -h /

# Calculate space recovered
# (handled by scripts/cleanup_report.py)

Report format:

✅ Cleanup Complete!

Before: 450 GB used (90%)
After:  385 GB used (77%)
━━━━━━━━━━━━━━━━━━━━━━━━
Recovered: 65 GB

Breakdown:
- System caches:        45 GB
- Downloads:            12 GB
- Homebrew cache:        5 GB
- Application remnants:  3 GB

⚠️ Notes:
- Some applications may take longer to launch on first run
- Deleted items cannot be recovered unless you have Time Machine backup
- Consider running this cleanup monthly

💡 Maintenance Tips:
- Set up automatic Homebrew cleanup: `brew cleanup` weekly
- Review Downloads folder monthly
- Enable "Empty Trash Automatically" in Finder preferences

Bonus: Dockerfile Optimization Discoveries

When image analysis reveals oversized images, suggest multi-stage build optimization. See the before/after example and key techniques in references/docker_analysis.md.

⚠️ 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:

⚠️ This operation requires administrator privileges.

Please run this command manually:
  sudo rm -rf /Library/Caches/*

⚠️ You'll be asked for your password.

💡 Backup Recommendation

Before executing any cleanup >10GB, recommend:

💡 Safety Tip:
Before cleaning XX GB, consider creating a Time Machine backup.

Quick backup check:
  tmutil latestbackup

If no recent backup, run:
  tmutil startbackup

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:

docker volume ls
docker volume inspect <volume_name>

Resources

scripts/

• analyze_caches.py - Scan and categorize cache directories
• find_app_remnants.py - Detect orphaned application data
• analyze_large_files.py - Find large files with smart filtering
• analyze_dev_env.py - Scan development environment resources
• safe_delete.py - Interactive deletion with confirmation
• cleanup_report.py - Generate before/after reports

references/

• cleanup_targets.md - Detailed explanations of each cleanup target
• mole_integration.md - How to use Mole, plus the multi-layer TUI exploration walkthrough
• docker_analysis.md - Docker deep-analysis workflow (Step 2A-2C) and Dockerfile optimization
• report_templates.md - Detailed report templates (object-level Docker tables, full report layout)
• safety_rules.md - 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. 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. Provide the command for the user to run themselves: rm -rf ~/Library/Caches/* (per Core Principle 9, do not auto-execute) 7. After the user runs it, verify with df -h / and report: "Recovered 45 GB"

Example 2: Development Environment Cleanup

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

Workflow: 1. Run scripts/analyze_dev_env.py 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. Run scripts/analyze_large_files.py --threshold 100MB 2. Present top 20 large files with context 3. Categorize: videos, datasets, archives, disk images 4. Let user decide what to delete 5. Provide deletion commands for the user to run (or use scripts/safe_delete.py for interactive per-item confirmation) 6. Suggest archiving to external drive

Best Practices

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.

macOS Cleanup Targets Reference

Detailed explanations of cleanup targets, their safety levels, and impact.

System Caches

~/Library/Caches

What it is: Application-level cache storage for user applications.

Contents:

• Browser caches (Chrome, Firefox, Safari)
• Application temporary files
• Download caches
• Thumbnail caches
• Font caches

Safety: 🟢 Safe to delete

Impact:

• Apps may be slower on first launch after deletion
• Websites may load slower on first visit (need to re-download assets)
• No data loss (caches are regenerated)

Size: Typically 10-100 GB depending on usage

Cleanup command:

rm -rf ~/Library/Caches/*

/Library/Caches

What it is: System-level cache storage (shared across all users).

Safety: 🟢 Safe to delete (requires sudo)

Impact: Same as user caches, but system-wide

Cleanup command:

sudo rm -rf /Library/Caches/*

Package Manager Caches

Homebrew Cache

Location: $(brew --cache) (typically ~/Library/Caches/Homebrew)

What it is: Downloaded package installers and build artifacts

Safety: 🟢 Safe to delete

Impact: Will need to re-download packages on next install/upgrade

Cleanup:

brew cleanup -s          # Safe cleanup (removes old versions)
brew cleanup --prune=all # Aggressive cleanup (removes all cached downloads)

npm Cache

Location: ~/.npm or configured cache directory

Safety: 🟢 Safe to delete

Impact: Packages will be re-downloaded when needed

Cleanup:

npm cache clean --force

pip Cache

Location: ~/Library/Caches/pip (macOS)

Safety: 🟢 Safe to delete

Impact: Packages will be re-downloaded when needed

Cleanup:

pip cache purge
# or for pip3
pip3 cache purge

Application Logs

~/Library/Logs

What it is: Application log files

Safety: 🟢 Safe to delete

Impact: Loss of diagnostic information (only matters if debugging)

Typical size: 1-20 GB

Cleanup:

rm -rf ~/Library/Logs/*

/var/log (System Logs)

What it is: System and service log files

Safety: 🟢 Safe to delete old logs (requires sudo)

Impact: Loss of system diagnostic history

Note: macOS automatically rotates logs, manual deletion rarely needed

Application Data

~/Library/Application Support

What it is: Persistent application data, settings, and databases

Safety: 🟡 Caution required

Contains:

• Application databases
• User preferences and settings
• Downloaded content
• Plugins and extensions
• Save games

When safe to delete:

• Application is confirmed uninstalled
• Folder belongs to trial software no longer used
• Folder is for outdated version of app (check first!)

When to KEEP:

• Active applications
• Any folder you're uncertain about

Recommendation: Use find_app_remnants.py to identify orphaned data

~/Library/Containers

What it is: Sandboxed application data (for App Store apps)

Safety: 🟡 Caution required

Same rules as Application Support - only delete for uninstalled apps

~/Library/Preferences

What it is: Application preference files (.plist)

Safety: 🟡 Caution required

Impact of deletion: App returns to default settings

When to delete:

• App is confirmed uninstalled
• Troubleshooting a misbehaving app (as last resort)

Development Environment

Docker

ABSOLUTE RULE: NEVER use any prune command (docker image prune, docker volume prune, docker system prune, docker container prune). Always delete by specifying exact object IDs or names.

Images

What it is: Container images (base OS + application layers)

Safety: 🟡 Requires per-image verification

Analysis:

# List all images sorted by size
docker images --format "table {{.ID}}\t{{.Repository}}:{{.Tag}}\t{{.Size}}\t{{.CreatedSince}}" | sort -k3 -h -r

# Identify dangling images
docker images -f "dangling=true" --format "{{.ID}}\t{{.Size}}\t{{.CreatedSince}}"

# For EACH image, verify no container references it
docker ps -a --filter "ancestor=<IMAGE_ID>" --format "{{.Names}}\t{{.Status}}"

Cleanup (only after per-image verification):

# Remove specific images by ID
docker rmi a02c40cc28df 555434521374 f471137cd508

Containers

What it is: Running or stopped container instances

Safety: 🟡 Stopped containers may be restarted -- verify with user

Analysis:

docker ps -a --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Size}}"

Cleanup (only after user confirms each container/project):

# Remove specific containers by name
docker rm container-name-1 container-name-2

Volumes

What it is: Persistent data storage for containers

Safety: 🔴 CAUTION - May contain databases, user uploads, and irreplaceable data

Analysis:

# List all volumes
docker volume ls

# Check which container uses each volume
docker ps -a --filter "volume=<VOLUME_NAME>" --format "{{.Names}}\t{{.Status}}"

# CRITICAL: For database volumes (mysql, postgres, redis in name), inspect contents
docker run --rm -v <VOLUME_NAME>:/data alpine ls -la /data
docker run --rm -v <VOLUME_NAME>:/data alpine du -sh /data/*

Cleanup (only after per-volume confirmation, database volumes require content inspection):

# Remove specific volumes by name
docker volume rm project-mysql-data project-redis-data

Build Cache

What it is: Intermediate build layers

Safety: 🟢 Safe to delete (rebuilds just take longer)

Note: docker builder prune is the ONE exception to the prune prohibition -- build cache contains only intermediate layers, never user data.

Cleanup:

docker builder prune -a

node_modules

What it is: Installed npm packages for Node.js projects

Safety: 🟢 Safe to delete (can be regenerated)

Impact: Need to run npm install to restore

Finding large node_modules:

find ~ -name "node_modules" -type d -prune -print 2>/dev/null | while read dir; do
  du -sh "$dir"
done | sort -hr

Cleanup:

# For old projects
rm -rf /path/to/old-project/node_modules

Python Virtual Environments

What it is: Isolated Python environments

Location: venv/, .venv/, env/ in project directories

Safety: 🟢 Safe to delete (can be recreated)

Impact: Need to recreate virtualenv and reinstall packages

Finding venvs:

find ~ -type d -name "venv" -o -name ".venv" 2>/dev/null

Git Repositories (.git directories)

What it is: Git version control data

Safety: 🟡 Depends on use case

When SAFE to delete:

• Project is archived and you have remote backup
• You only need final code, not history

When to KEEP:

• Active development
• No remote backup exists
• You might need the history

Cleanup (convert to plain folder, lose history):

rm -rf /path/to/old-project/.git

Large Files

Downloads Folder

What it is: Files downloaded from internet

Safety: 🟡 User judgment required

Common cleanable items:

• Old installers (.dmg, .pkg)
• Zip archives already extracted
• Temporary downloads
• Duplicate files

Check before deleting: Might contain important downloads

Disk Images (.dmg, .iso)

What it is: Mountable disk images, often installers

Safety: 🟢 Safe to delete after installation

Typical location: ~/Downloads

Cleanup: Delete .dmg files for already-installed apps

Archives (.zip, .tar.gz)

What it is: Compressed archives

Safety: 🟡 Check if extracted

Before deleting: Verify contents are extracted elsewhere

Old iOS Backups

Location: ~/Library/Application Support/MobileSync/Backup/

What it is: iTunes/Finder iPhone/iPad backups

Safety: 🟡 Caution - backup data

Check:

ls -lh ~/Library/Application\ Support/MobileSync/Backup/

Cleanup: Delete old backups via Finder preferences, not manually

Old Time Machine Local Snapshots

What it is: Local Time Machine backups

Safety: 🟢 Safe - macOS manages automatically

macOS automatically deletes these when disk space is low

Check:

tmutil listlocalsnapshots /

Manual cleanup (rarely needed):

tmutil deletelocalsnapshots <snapshot_date>

What to NEVER Delete

User Data Directories

• ~/Documents
• ~/Desktop
• ~/Pictures
• ~/Movies
• ~/Music

System Files

• /System
• /Library/Apple (unless you know what you're doing)
• /private/etc

Security & Credentials

• ~/.ssh (SSH keys)
• ~/Library/Keychains (passwords, certificates)
• Any files containing credentials

Active Databases

• *.db, *.sqlite files for running applications
• Docker volumes in active use

Safety Checklist

Before deleting ANY directory:

1. ✅ Do you know what it is? 2. ✅ Is the application truly uninstalled? 3. ✅ Have you checked if it's in use? (lsof, Activity Monitor) 4. ✅ Do you have a Time Machine backup? 5. ✅ Have you confirmed with the user?

When in doubt, DON'T DELETE.

Recovery Options

Trash vs. Permanent Deletion

Use Trash when possible:

# Move to trash (recoverable)
osascript -e 'tell app "Finder" to move POSIX file "/path/to/file" to trash'

Permanent deletion:

# Cannot be recovered without Time Machine
rm -rf /path/to/file

Time Machine

If you deleted something important:

1. Open Time Machine 2. Navigate to parent directory 3. Select date before deletion 4. Restore

File Recovery Tools

If no Time Machine backup:

• Disk Drill (commercial)
• PhotoRec (free, for photos)
• TestDisk (free, for files)

Note: Success rate depends on how recently deleted and disk usage since deletion.

Docker Deep Analysis

Detailed Docker analysis workflow referenced from SKILL.md Step 2. Use this when development-environment cleanup involves Docker images, containers, volumes, or build cache.

Step 2A: Docker Deep Analysis

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

Agent 1 — Images:

# List all images sorted by size
docker images --format "table {{.ID}}\t{{.Repository}}:{{.Tag}}\t{{.Size}}\t{{.CreatedSince}}" | sort -k3 -h -r

# Identify dangling images (no tag)
docker images -f "dangling=true" --format "{{.ID}}\t{{.Size}}\t{{.CreatedSince}}"

# For each image, check if any container references it
docker ps -a --filter "ancestor=<IMAGE_ID>" --format "{{.Names}}\t{{.Status}}"

Agent 2 — Containers and Volumes:

# All containers with status
docker ps -a --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Size}}"

# All volumes with size
docker system df -v | grep -A 1000 "VOLUME NAME"

# Identify dangling volumes
docker volume ls -f dangling=true

# For each volume, check which container uses it
docker ps -a --filter "volume=<VOLUME_NAME>" --format "{{.Names}}"

Agent 3 — System Level:

# Docker disk usage summary
docker system df

# Build cache
docker builder du

# Container logs size
for c in $(docker ps -a --format "{{.Names}}"); do
  echo "$c: $(docker inspect --format='{{.LogPath}}' $c | xargs ls -lh 2>/dev/null | awk '{print $5}')"
done

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:

# Logical size (can show 8TB+, meaningless)
ls -lh ~/Library/OrbStack/data/data.img.raw

# Actual disk usage (this is what matters)
du -h ~/Library/OrbStack/data/data.img.raw

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:

# Verify no container (running or stopped) references the image
docker ps -a --filter "ancestor=<IMAGE_ID>" --format "{{.Names}}\t{{.Status}}"

# If empty → safe to delete with: docker rmi <IMAGE_ID>

For Volumes:

# Verify no container mounts the volume
docker ps -a --filter "volume=<VOLUME_NAME>" --format "{{.Names}}"

# If empty → check if database volume (see below)
# If not database → safe to delete with: docker volume rm <VOLUME_NAME>

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

# Inspect database volume contents with temporary container
docker run --rm -v <VOLUME_NAME>:/data alpine ls -la /data
docker run --rm -v <VOLUME_NAME>:/data alpine du -sh /data/*

Only delete after user confirms the data is not needed.

Bonus: Dockerfile Optimization Discoveries

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

# Before: 884 MB (full build environment in final image)
FROM node:20
COPY . .
RUN npm ci && npm run build
CMD ["node", "dist/index.js"]

# After: ~150 MB (only runtime in final image)
FROM node:20 AS builder
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-slim
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

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

Mole Integration Guide

How to integrate Mole with the macOS Cleaner skill.

About Mole

Mole is a command-line interface (CLI) tool for macOS disk cleanup. It provides:

• Interactive terminal-based disk usage analysis
• Comprehensive cleanup for caches, logs, and application remnants
• Developer environment cleanup (Docker, npm, pip, Homebrew, etc.)
• Safe deletion with preview (--dry-run)

Repository: https://github.com/tw93/Mole

Critical: TTY Environment Required

IMPORTANT: Mole requires a TTY (terminal) environment for interactive commands. When running Mole from automated environments (scripts, Claude Code, CI/CD), use tmux to provide a proper TTY.

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

# Send command to tmux session
tmux send-keys -t mole 'mo analyze' Enter

# Capture output
tmux capture-pane -t mole -p

# Clean up when done
tmux kill-session -t mole

Installation

Check if Mole is Installed

# Check if mole command exists
which mo && mo --version

Expected output:

/opt/homebrew/bin/mo
Mole version X.Y.Z
macOS: XX.X
Architecture: arm64
...

Installation via Homebrew (Recommended)

brew install tw93/tap/mole

Version Check and Update

IMPORTANT: Always check if Mole is up-to-date before use. The tool updates frequently with bug fixes and new features.

# Check current vs latest version
brew info tw93/tap/mole | head -5

# If outdated, upgrade
brew upgrade tw93/tap/mole

Available Commands

CRITICAL: Only use mo --help to view help. Do NOT append --help to other commands as it may cause unexpected behavior.

# View all commands (SAFE - the only help command)
mo --help

Available commands from mo --help:

mo analyze vs mo clean --dry-run

CRITICAL: These are two different tools with different purposes. Use the right tool for the job.

Comparison Table

When to Use Each

Use `mo analyze` when:

• User asks "What's taking up space?" or "Where is my disk space going?"
• Need to understand storage consumption patterns
• Want to explore specific directories interactively
• Investigating unexpected disk usage

Use `mo clean --dry-run` when:

• Already know what's consuming space (after mo analyze)
• User is ready to see cleanup recommendations
• Need a quick preview of what can be cleaned
• Preparing to run mo clean for actual cleanup

Workflow Recommendation

Step 1: mo analyze (understand the problem)
    ↓
Step 2: Present findings to user
    ↓
Step 3: mo clean --dry-run (show cleanup options)
    ↓
Step 4: User confirms cleanup categories
    ↓
Step 5: User runs mo clean (actual cleanup)

Common Mistake

# ❌ WRONG: Jumping straight to cleanup preview
tmux send-keys -t mole 'mo clean --dry-run' Enter
# This only shows cleanup-eligible items, not the full picture

# ✅ CORRECT: Start with disk analysis
tmux send-keys -t mole 'mo analyze' Enter
# This shows where ALL disk space is going

Interactive TUI Navigation (mo analyze)

mo analyze provides an interactive tree view. Navigate using tmux key sequences:

# Start analysis
tmux send-keys -t mole 'mo analyze' Enter

# Wait for scan to complete (5-10 minutes for Home directory!)
sleep 300  # 5 minutes for large directories

# Capture current view
tmux capture-pane -t mole -p

# Navigate down to next item
tmux send-keys -t mole Down

# Expand/enter selected directory
tmux send-keys -t mole Enter

# Go back up
tmux send-keys -t mole Up

# Quit the TUI
tmux send-keys -t mole 'q'

Safe Analysis Workflow

Step 1: Check Version First

# Always ensure latest version
brew info tw93/tap/mole | head -3

Step 2: Create TTY Environment

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

Step 3: Run Analysis (Safe Commands Only)

# Disk analysis - SAFE, read-only
tmux send-keys -t mole 'mo analyze' Enter

# Wait for scan to complete (be patient!)
sleep 30  # Home directory scanning can take several minutes

# Capture results
tmux capture-pane -t mole -p

Step 4: Preview Cleanup (No Actual Deletion)

# Preview what would be cleaned - SAFE
tmux send-keys -t mole 'mo clean --dry-run' Enter
sleep 10
tmux capture-pane -t mole -p

Step 5: User Confirmation Required

NEVER execute mo clean without explicit user confirmation. Always: 1. Show the --dry-run preview results to user 2. Wait for user to confirm each category 3. User runs the actual cleanup command themselves

Safety Principles

0. Value Over Vanity (Most Important)

Your goal is NOT to maximize cleaned space. Your goal is to identify truly useless items while preserving valuable caches.

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

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

See SKILL.md sections "Anti-Patterns: What NOT to Delete" and "What IS Safe to Delete" for the full tables of items to keep vs items safe to remove.

1. Never Execute Dangerous Commands Automatically

# ❌ NEVER do this automatically
mo clean
mo uninstall
mo purge
docker system prune -a --volumes
docker volume prune -f
rm -rf ~/Library/Caches/*

# ✅ ALWAYS use preview/dry-run first
mo clean --dry-run

2. Patience is Critical

• mo analyze on large home directories can take 5-10 minutes
• Do NOT interrupt or skip slow scans
• Report progress to user regularly
• Wait for complete results before making decisions

3. User Executes Cleanup

After analysis and confirmation:

Present findings to user, then provide command for them to run:

"Based on the analysis, you can reclaim approximately 30GB.
To proceed, please run this command in your terminal:

    mo clean

You will be prompted to confirm each category interactively."

Mole Command Details

mo analyze

Interactive disk usage explorer. Scans these locations:

• Home directory (~)
• App Library (~/Library/Application Support)
• Applications (/Applications)
• System Library (/Library)
• Volumes

Usage in tmux:

tmux send-keys -t mole 'mo analyze' Enter

# Navigate with arrow keys (send via tmux)
tmux send-keys -t mole Down  # Move to next item
tmux send-keys -t mole Enter # Select/expand item
tmux send-keys -t mole 'q'   # Quit

mo clean --dry-run

Preview cleanup without deletion. Shows:

• User essentials (caches, logs, trash)
• macOS system caches
• Browser caches
• Developer tool caches (npm, pip, uv, Homebrew, Docker, etc.)

Whitelist: Mole maintains a whitelist of protected patterns. Check with:

mo clean --whitelist

mo status

System health monitoring (CPU, memory, disk, network). Requires TTY for real-time display.

mo purge

Cleans old project build artifacts (node_modules, target, venv, etc.) from configured directories.

Check/configure scan paths:

mo purge --paths

Integration with Claude Code

Recommended Workflow

1. Version check: Ensure Mole is installed and up-to-date 2. TTY setup: Create tmux session for interactive commands 3. Analysis: Run mo analyze or mo clean --dry-run 4. Progress reporting: Inform user of scan progress 5. Present findings: Show structured results to user 6. User confirmation: Wait for explicit approval 7. Provide command: Give user the command to run themselves

Example Session

# 1. Check version
$ brew info tw93/tap/mole | head -3
# Output: tw93/tap/mole: stable 1.20.0
# Installed: 1.13.13 -> needs upgrade

# 2. Upgrade if needed
$ brew upgrade tw93/tap/mole

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

# 4. Run dry-run analysis
$ tmux send-keys -t mole 'mo clean --dry-run' Enter

# 5. Wait and capture output
$ sleep 15 && tmux capture-pane -t mole -p

# 6. Present to user:
"""
📊 Cleanup Preview (dry-run - no files deleted)

User essentials:
  - User app cache: 16.67 GB
  - User app logs: 102.3 MB
  - Trash: 642.9 MB

Developer tools:
  - uv cache: 9.96 GB
  - npm cache: (pending)
  - Docker: (pending)

Total recoverable: ~27 GB

To proceed with cleanup, please run in your terminal:
    mo clean
"""

Troubleshooting

"device not configured" Error

Cause: Command run without TTY environment.

Solution: Use tmux:

tmux new-session -d -s mole
tmux send-keys -t mole 'mo status' Enter

Scan Stuck on "pending"

Cause: Large directories take time to scan.

Solution: Be patient. Home directory with many files can take 5-10 minutes. Monitor progress:

# Check if still scanning (spinner animation in output)
tmux capture-pane -t mole -p | tail -10

Non-Interactive Mode Auto-Executes

WARNING: Some Mole commands may auto-execute in non-TTY environments without confirmation!

Solution: ALWAYS use tmux for ANY Mole command, even help:

# ❌ DANGEROUS - may auto-execute
mo clean --help  # Might run cleanup instead of showing help!

# ✅ SAFE - use mo --help only
mo --help  # The ONLY safe help command

Version Mismatch

Cause: Local version outdated.

Solution:

# Check versions
brew info tw93/tap/mole

# Upgrade
brew upgrade tw93/tap/mole

Summary

Key Points: 1. Mole is a CLI tool, not a GUI application 2. Install via brew install tw93/tap/mole 3. Always check version before use 4. Use tmux for all interactive commands 5. mo --help is the ONLY safe help command 6. Never auto-execute cleanup commands 7. Be patient - scans take time 8. User runs cleanup - provide command, don't execute

Multi-Layer Deep Exploration with Mole

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

Navigation Commands

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

# Start analysis
tmux send-keys -t mole 'mo analyze' Enter

# Wait for initial scan
sleep 8 && tmux capture-pane -t mole -p

# Navigation keys (send via tmux)
tmux send-keys -t mole Enter    # Enter/expand selected directory
tmux send-keys -t mole Left     # Go back to parent directory
tmux send-keys -t mole Down     # Move to next item
tmux send-keys -t mole Up       # Move to previous item
tmux send-keys -t mole 'q'      # Quit TUI

# Capture current view
tmux capture-pane -t mole -p

Multi-Layer Exploration Workflow

Step 1: Top-level overview

# Start mo analyze, wait for initial menu
tmux send-keys -t mole 'mo analyze' Enter
sleep 8 && tmux capture-pane -t mole -p

# Example output:
# 1. Home           289.4 GB (58.5%)
# 2. App Library    145.2 GB (29.4%)
# 3. Applications    49.5 GB (10.0%)
# 4. System Library  10.3 GB (2.1%)

Step 2: Enter largest directory (Home)

tmux send-keys -t mole Enter
sleep 10 && tmux capture-pane -t mole -p

# Example output:
# 1. Library       144.4 GB (49.9%)
# 2. Workspace      52.0 GB (18.0%)
# 3. .cache         19.3 GB (6.7%)
# 4. Applications   17.0 GB (5.9%)
# ...

Step 3: Drill into specific directories

# Go to .cache (3rd item: Down Down Enter)
tmux send-keys -t mole Down Down Enter
sleep 5 && tmux capture-pane -t mole -p

# Example output:
# 1. uv           10.3 GB (55.6%)
# 2. modelscope    5.5 GB (29.5%)
# 3. huggingface   887.8 MB (4.7%)

Step 4: Navigate back and explore another branch

# Go back to parent
tmux send-keys -t mole Left
sleep 2

# Navigate to different directory
tmux send-keys -t mole Down Down Down Down Enter  # Go to .npm
sleep 5 && tmux capture-pane -t mole -p

Step 5: Deep dive into Library

# Back to Home, then into Library
tmux send-keys -t mole Left
tmux send-keys -t mole Up Up Up Up Up Up Enter  # Go to Library
sleep 10 && tmux capture-pane -t mole -p

# Example output:
# 1. Application Support  37.1 GB
# 2. Containers          35.4 GB
# 3. Developer           17.8 GB  ← Xcode is here
# 4. Caches               8.2 GB

Recommended Exploration Path

For comprehensive analysis, follow this exploration tree:

mo analyze
├── Home (Enter)
│   ├── Library (Enter)
│   │   ├── Developer (Enter) → Xcode/DerivedData, iOS DeviceSupport
│   │   ├── Caches (Enter) → Playwright, JetBrains, etc.
│   │   └── Application Support (Enter) → App data
│   ├── .cache (Enter) → uv, modelscope, huggingface
│   ├── .npm (Enter) → _cacache, _npx
│   ├── Downloads (Enter) → Large files to review
│   ├── .Trash (Enter) → Confirm trash contents
│   └── miniconda3/other dev tools (Enter) → Check last used time
├── App Library → Usually overlaps with ~/Library
└── Applications → Installed apps

Time Expectations

Example Complete Session

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

# 2. Start analysis and get overview
tmux send-keys -t mole 'mo analyze' Enter
sleep 8 && tmux capture-pane -t mole -p

# 3. Enter Home
tmux send-keys -t mole Enter
sleep 10 && tmux capture-pane -t mole -p

# 4. Enter .cache to see dev caches
tmux send-keys -t mole Down Down Enter
sleep 5 && tmux capture-pane -t mole -p

# 5. Back to Home, then to .npm
tmux send-keys -t mole Left
sleep 2
tmux send-keys -t mole Down Down Down Down Enter
sleep 5 && tmux capture-pane -t mole -p

# 6. Back to Home, enter Library
tmux send-keys -t mole Left
sleep 2
tmux send-keys -t mole Up Up Up Up Up Up Enter
sleep 10 && tmux capture-pane -t mole -p

# 7. Enter Developer to see Xcode
tmux send-keys -t mole Down Down Down Enter
sleep 5 && tmux capture-pane -t mole -p

# 8. Enter Xcode
tmux send-keys -t mole Enter
sleep 5 && tmux capture-pane -t mole -p

# 9. Enter DerivedData to see projects
tmux send-keys -t mole Enter
sleep 5 && tmux capture-pane -t mole -p

# 10. Cleanup
tmux kill-session -t mole

Key Insights from Exploration

After multi-layer exploration, you will discover:

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

Report Templates

Detailed report templates referenced from SKILL.md. The core report format and classification legend live in SKILL.md; this file holds the longer, fill-in-the-blank templates so they load only when needed.

Docker Report: Required Object-Level Detail

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

#### Dangling Images (no tag, no container references)
| Image ID | Size | Created | Safe? |
|----------|------|---------|-------|
| a02c40cc28df | 884 MB | 2 months ago | ✅ No container uses it |
| 555434521374 | 231 MB | 3 months ago | ✅ No container uses it |

#### Stopped Containers
| Name | Image | Status | Size |
|------|-------|--------|------|
| ragflow-mysql | mysql:8.0 | Exited 2 weeks ago | 1.2 GB |

#### Volumes
| Volume | Size | Mounted By | Contains |
|--------|------|------------|----------|
| ragflow_mysql_data | 1.8 GB | ragflow-mysql | MySQL databases |
| redis_data | 500 MB | (none - dangling) | Redis dump |

#### 🔴 Database Volumes Requiring Inspection
| Volume | Inspected Contents | User Decision |
|--------|--------------------|---------------|
| ragflow_mysql_data | 8 databases, 45 tables | Still need? |

High-Quality Report Template (Chinese)

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

## 📊 磁盘空间深度分析报告

**分析日期**: YYYY-MM-DD
**使用工具**: Mole CLI + 多层目录探索
**分析原则**: 安全第一，价值优于虚荣

---

### 总览

| 区域 | 总占用 | 关键发现 |
|------|--------|----------|
| **Home** | XXX GB | Library占一半(XXX GB) |
| **App Library** | XXX GB | 与Home/Library重叠统计 |
| **Applications** | XXX GB | 应用本体 |

---

### 🟢 绝对安全可删除 (约 X.X GB)

| 项目 | 大小 | 位置 | 删除后影响 | 清理命令 |
|------|------|------|-----------|---------|
| **废纸篓** | XXX MB | ~/.Trash | 无 - 你已决定删除的文件 | 清空废纸篓 |
| **npm _npx** | X.X GB | ~/.npm/_npx | 下次 npx 命令重新下载 | `rm -rf ~/.npm/_npx` |
| **Homebrew 旧版本** | XX MB | /opt/homebrew | 无 - 已被新版本替代 | `brew cleanup --prune=0` |

**废纸篓内容预览**:
- [列出主要文件]

---

### 🟡 需要你确认的项目

#### 1. [项目名] (X.X GB) - [状态描述]

| 子目录 | 大小 | 最后使用 |
|--------|------|----------|
| [子目录1] | X.X GB | >X个月 |
| [子目录2] | X.X GB | >X个月 |

**问题**: [需要用户回答的问题]

---

#### 2. Downloads 中的旧文件 (X.X GB)

| 文件/目录 | 大小 | 年龄 | 建议 |
|-----------|------|------|------|
| [文件1] | X.X GB | - | [建议] |
| [文件2] | XXX MB | >X个月 | [建议] |

**建议**: 手动检查 Downloads，删除已不需要的文件。

---

#### 3. 停用的 Docker 项目 Volumes

| 项目前缀 | 可能包含的数据 | 需要你确认 |
|---------|--------------|-----------|
| `project1_*` | MySQL, Redis | 还在用吗？ |
| `project2_*` | Postgres | 还在用吗？ |

**注意**: 我不会使用 `docker volume prune -f`，只会在你确认后删除特定项目的 volumes。

---

### 🔴 不建议删除的项目 (有价值的缓存)

| 项目 | 大小 | 为什么要保留 |
|------|------|-------------|
| **Xcode DerivedData** | XX GB | [项目名]的编译缓存，删除后下次构建需要X分钟 |
| **npm _cacache** | X.X GB | 所有下载过的 npm 包，删除后需要重新下载 |
| **~/.cache/uv** | XX GB | Python 包缓存，重新下载在中国网络下很慢 |
| [其他有价值的缓存] | X.X GB | [保留原因] |

---

### 📋 其他发现

| 项目 | 大小 | 说明 |
|------|------|------|
| **OrbStack/Docker** | XX GB | 正常的 VM/容器占用 |
| [其他发现] | X.X GB | [说明] |

---

### ✅ 推荐操作

**立即可执行** (无需确认):

1. 清空废纸篓 (XXX MB)

手动: Finder → 清空废纸篓

2. npm _npx (X.X GB)

rm -rf ~/.npm/_npx

3. Homebrew 旧版本 (XX MB)

brew cleanup --prune=0

**预计释放**: ~X.X GB

---

**需要你确认后执行**:

1. **[项目1]** - [确认问题]
2. **[项目2]** - [确认问题]
3. **Docker 项目** - 告诉我哪些项目确定不用了

Safety Rules for macOS Cleanup

Critical safety guidelines to prevent data loss and system damage.

Golden Rules

Rule 1: Never Delete Without Confirmation

ALWAYS ask user before deleting ANY file or directory.

Bad:

shutil.rmtree(cache_dir)  # Immediately deletes

Good:

if confirm_delete(cache_dir, size, description):
    shutil.rmtree(cache_dir)
else:
    print("Skipped")

Rule 2: Explain Before Deleting

Users should understand:

• What is being deleted
• Why it's safe (or not safe)
• Impact of deletion
• Recoverability (can it be restored?)

Rule 3: When in Doubt, Don't Delete

If uncertain about safety: DON'T DELETE.

Ask user to verify instead.

Rule 4: High-Risk Paths Are Hard Blocks

safe_delete.py must refuse dangerous system and credential paths before confirmation and inside the delete function. A warning is not enough for:

• /, /System, /usr, /bin, /etc
• ~/.ssh, ~/.aws, ~/.gnupg
• ~/Library/Keychains

These paths and their descendants are blocked even when the user selects all in batch mode.

Rule 5: Suggest Backups for Large Deletions

Before deleting >10 GB, recommend Time Machine backup.

Rule 6: Docker Prune Prohibition

NEVER use any Docker prune command. This includes:

• docker image prune / docker image prune -a
• docker container prune
• docker volume prune / docker volume prune -f
• docker system prune / docker system prune -a --volumes

Why: Prune commands operate on categories, not specific objects. They can silently destroy database volumes, user uploads, and container state that the user intended to keep. A user who loses their MySQL data because of a prune command will never trust this tool again.

Correct approach: Always specify exact object IDs or names:

# Images: delete by specific ID
docker rmi a02c40cc28df 555434521374

# Containers: delete by specific name
docker rm container-name-1 container-name-2

# Volumes: delete by specific name
docker volume rm project-mysql-data project-redis-data

Rule 7: Double-Check Verification Protocol

Before deleting ANY Docker object, perform independent cross-verification. This applies to images, volumes, and containers.

Key requirements:

• For images: verify no container (running or stopped) references the image
• For volumes: verify no container mounts the volume
• For database volumes (name contains mysql, postgres, redis, mongo, mariadb): MANDATORY content inspection with a temporary container
• Even if Docker reports a volume as "dangling", the data inside may be valuable

See SKILL.md Step 4 for the complete verification commands and database volume inspection workflow.

Rule 8: Use Trash When Possible

Prefer moving to Trash over permanent deletion:

# Recoverable
osascript -e 'tell app "Finder" to move POSIX file "/path/to/file" to trash'

# Permanent (use only when confirmed safe)
rm -rf /path/to/file

Never Delete These

System Directories

User Data

Security & Credentials

Active Databases

Running Applications

Require Extra Confirmation

Large Deletions

Threshold: >10 GB

Action: Warn user and suggest Time Machine backup

Example:

⚠️ This operation will delete 45 GB of data.

💡 Recommendation:
   Create a Time Machine backup first.

   Check last backup:
     tmutil latestbackup

   Create backup now:
     tmutil startbackup

Proceed without backup? [y/N]:

System-Wide Caches

Paths: /Library/Caches, /var/log

Action: Require manual sudo command (don't execute directly)

Example:

⚠️ This operation requires administrator privileges.

Please run this command manually:
  sudo rm -rf /Library/Caches/*

⚠️ You will be asked for your password.

Reason:

• Requires elevated privileges
• User should be aware of system-wide impact
• Audit trail (user types password)

Docker Objects (Images, Containers, Volumes)

Action: List every object individually. Use precision deletion only (see Rule 6 and Rule 7).

NEVER use prune commands. Always specify exact IDs/names.

Example for volumes:

Docker volumes found:
  postgres_data    (1.2 GB)  - Contains PostgreSQL database
  redis_data       (500 MB)  - Contains Redis cache data
  app_uploads      (3 GB)    - Contains user-uploaded files

Database volumes inspected with temporary container:
  postgres_data: 8 databases, 45 tables, last modified 2 days ago
  redis_data: 12 MB dump.rdb

Confirm EACH volume individually:
  Delete postgres_data? [y/N]:
  Delete redis_data? [y/N]:
  Delete app_uploads? [y/N]:

Deletion commands (after confirmation):
  docker volume rm postgres_data redis_data

Application Preferences

Path: ~/Library/Preferences/*.plist

Action: Warn that app will reset to defaults

Example:

⚠️ Deleting preferences will reset the app to defaults.

Impact:
- All settings will be lost
- Custom configurations will be reset
- May need to re-enter license keys

Only delete if:
- App is misbehaving (troubleshooting)
- App is confirmed uninstalled

Proceed? [y/N]:

Safety Checks Before Deletion

Check 1: Path Exists

if not os.path.exists(path):
    print(f"❌ Path does not exist: {path}")
    return False

Check 2: Not a Blocked Path

blocked_paths = [
    '/System', '/Library/Apple', '/etc', '/private/etc',
    '/usr', '/bin', '/sbin', '/private/var/db',
    '~/.ssh', '~/.aws', '~/.gnupg', '~/Library/Keychains',
]

expanded_path = os.path.realpath(os.path.expanduser(path))
if expanded_path == '/':
    print("❌ Cannot delete root path")
    return False

for blocked_path in blocked_paths:
    expanded_blocked = os.path.realpath(os.path.expanduser(blocked_path))
    if expanded_path == expanded_blocked or expanded_path.startswith(expanded_blocked + os.sep):
        print(f"❌ Cannot delete blocked path: {path}")
        return False

Check 3: Not User Data

user_data_paths = [
    '~/Documents', '~/Desktop', '~/Pictures',
    '~/Movies', '~/Music'
]

expanded_path = os.path.expanduser(path)
for data_path in user_data_paths:
    if expanded_path.startswith(os.path.expanduser(data_path)):
        print(f"⚠️ This is a user data directory: {path}")
        print("   Are you ABSOLUTELY sure? [type 'DELETE' to confirm]:")
        response = input().strip()
        if response != 'DELETE':
            return False

Check 4: Not in Use

def is_in_use(path):
    """Check if file/directory is in use."""
    try:
        result = subprocess.run(
            ['lsof', path],
            capture_output=True,
            text=True
        )
        # If lsof finds processes using the file, returncode is 0
        if result.returncode == 0:
            return True
        return False
    except:
        return False  # Assume not in use if check fails

if is_in_use(path):
    print(f"⚠️ Warning: {path} is currently in use")
    print("   Close the application first, then try again.")
    return False

Check 5: Permissions

def can_delete(path):
    """Check if we have permission to delete."""
    try:
        # Check parent directory write permission
        parent = os.path.dirname(path)
        return os.access(parent, os.W_OK)
    except:
        return False

if not can_delete(path):
    print(f"❌ No permission to delete: {path}")
    print("   You may need sudo, but be careful!")
    return False

Safe Deletion Workflow

def safe_delete(path, size, description):
    """
    Safe deletion workflow with all checks.

    Args:
        path: Path to delete
        size: Size in bytes
        description: Human-readable description

    Returns:
        (success, message)
    """
    # Safety checks
    if not os.path.exists(path):
        return (False, "Path does not exist")

    if is_system_path(path):
        return (False, "Cannot delete system path")

    if is_user_data(path):
        if not extra_confirm(path):
            return (False, "User cancelled")

    if is_in_use(path):
        return (False, "Path is in use")

    if not can_delete(path):
        return (False, "No permission")

    # Backup warning for large deletions
    if size > 10 * 1024 * 1024 * 1024:  # 10 GB
        if not confirm_large_deletion(size):
            return (False, "User cancelled")

    # Final confirmation
    if not confirm_delete(path, size, description):
        return (False, "User cancelled")

    # Execute deletion
    try:
        if os.path.isfile(path):
            os.unlink(path)
        else:
            shutil.rmtree(path)
        return (True, f"Deleted successfully ({format_size(size)} freed)")
    except Exception as e:
        return (False, f"Deletion failed: {str(e)}")

Error Handling

Permission Denied

except PermissionError:
    print(f"❌ Permission denied: {path}")
    print("   Try running with sudo (use caution!)")

Operation Not Permitted (SIP)

# macOS System Integrity Protection blocks some deletions
except OSError as e:
    if e.errno == 1:  # Operation not permitted
        print(f"❌ System Integrity Protection prevents deletion: {path}")
        print("   This is a protected system file.")
        print("   Do NOT attempt to bypass SIP unless you know what you're doing.")

Path Too Long

except OSError as e:
    if e.errno == 63:  # File name too long
        print(f"⚠️ Path too long, trying alternative method...")
        # Try using find + rm

Recovery Options

If User Accidentally Confirmed

Immediate action: Check Trash first

# Files may be in Trash
ls -lh ~/.Trash

Next: Time Machine

# Open Time Machine to date before deletion
tmutil browse

Last resort: File recovery tools

• Disk Drill (commercial)
• PhotoRec (free)
• TestDisk (free)

Note: Success rate depends on:

• How recently deleted
• How much disk activity since deletion
• Whether SSD (TRIM) or HDD

Preventing Accidents

1. Use Trash instead of rm when possible 2. Require Time Machine backup for >10 GB deletions 3. Test on small items first before batch operations 4. Show dry-run results before actual deletion

Red Flags to Watch For

User Requests

If user asks to:

• "Delete everything in ~/Library"
• "Clear all caches including system"
• "Delete all .log files on the entire system"
• "Remove all databases"

Response:

⚠️ This request is too broad and risky.

Let me help you with a safer approach:
1. Run analysis to identify specific targets
2. Review each category
3. Delete selectively with confirmation

This prevents accidental data loss.

Script Behavior

If script is about to:

• Delete >100 GB at once
• Delete entire directory trees without listing contents
• Run rm -rf / or similar dangerous commands
• Delete from system paths

Action: STOP and ask for confirmation

Testing Guidelines

Before Packaging

Test safety checks:

1. ✅ Attempt to delete system path → Should reject 2. ✅ Attempt to delete user data → Should require extra confirmation 3. ✅ Attempt to delete in-use file → Should warn 4. ✅ Attempt to delete without permission → Should fail gracefully 5. ✅ Large deletion → Should suggest backup

In Production

Always:

• Start with smallest items
• Confirm results after each deletion
• Monitor disk space before/after
• Ask user to verify important apps still work

Summary

Conservative Approach

When implementing cleanup:

1. Assume danger until proven safe 2. Explain everything to user 3. Confirm each step 4. Suggest backups for large operations 5. Use Trash when possible 6. Test thoroughly before packaging

Remember

"It's better to leave 1 GB of unnecessary files than to delete 1 MB of important data."

User trust is fragile. One bad deletion loses it forever.

Final Checklist

Before any deletion:

• [ ] Path is verified to exist
• [ ] Path is not a system path
• [ ] Path is not user data (or extra confirmed)
• [ ] Path is not in use
• [ ] User has been informed of impact
• [ ] User has explicitly confirmed
• [ ] Backup suggested for large deletions
• [ ] Error handling in place
• [ ] Recovery options documented

Only then: proceed with deletion.