claude-code-skills-reference/macos-cleaner/references/mole_integration.md

Mole Integration Guide

How to integrate Mole with the macOS Cleaner skill.

About Mole

Mole is a visual macOS disk cleanup tool with a native macOS interface. It provides:

• Visual disk usage analysis
• One-click cleanup for common targets
• Safe deletion with preview
• Native macOS design

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

When to Recommend Mole

Suggest Mole to users in these scenarios:

1. User Prefers Visual Interface

User: "I prefer clicking buttons rather than running commands"

Response:

I recommend using Mole alongside these scripts:

1. Use the analysis scripts to understand what's using space
2. Install Mole for visual cleanup: https://github.com/tw93/Mole
3. Use Mole's GUI to execute cleanup with visual confirmation

Would you like me to guide you through the analysis first?

2. Complex Cleanup Needs

User: "I have lots of cache files and don't want to run commands for each"

Response:

Mole can help with batch cleanup. It provides visual categories:

- System caches
- Application caches
- Log files
- Trash

Install Mole and you can review and clean multiple categories at once.

3. Ongoing Maintenance

User: "I want to clean my Mac regularly"

Response:

For regular maintenance, I recommend:

1. Keep Mole installed for weekly quick cleanups
2. Use our analysis scripts monthly for deep analysis
3. Use safe_delete.py for specific files/folders

This hybrid approach gives you both convenience and precision.

Installation

Check if Mole is Installed

if [ -d "/Applications/Mole.app" ]; then
  echo "✅ Mole is installed"
  open -a Mole
else
  echo "💡 Mole is not installed"
  echo "   Install from: https://github.com/tw93/Mole"
fi

Installation Methods

Method 1: Download from GitHub Releases

# Guide user to:
# 1. Visit https://github.com/tw93/Mole/releases
# 2. Download latest .dmg file
# 3. Open .dmg and drag Mole.app to /Applications

Method 2: Build from Source (if user is developer)

git clone https://github.com/tw93/Mole.git
cd Mole
# Follow build instructions in README

Workflow Integration

Hybrid Workflow: Scripts + Mole

Best practice: Use both tools for their strengths.

Step 1: Analysis with Scripts

Run comprehensive analysis:

# System analysis
python3 scripts/analyze_caches.py
python3 scripts/analyze_large_files.py --threshold 100
python3 scripts/find_app_remnants.py

# Developer analysis (if applicable)
python3 scripts/analyze_dev_env.py

This gives detailed reports with safety categorization.

Step 2: Review Findings

Present findings to user in readable format (see SKILL.md Step 4).

Step 3: Execute Cleanup

For different types of cleanup:

Option A: Use Mole (for batch operations)

• System caches: Use Mole's "System" category
• Application caches: Use Mole's "Applications" category
• Trash: Use Mole's "Trash" feature

Option B: Use Scripts (for precision)

• Large files: Use safe_delete.py with specific paths
• Application remnants: Use safe_delete.py with confirmed orphans
• Dev environment: Run cleanup commands directly

Option C: Manual (for sensitive items)

• Guide user to review in Finder
• User deletes manually

Example Integrated Session

🔍 Analysis Results

I've analyzed your Mac and found:
- System caches: 45 GB (safe to clean)
- Large files: 38 GB (need review)
- App remnants: 8 GB (medium confidence)
- Docker: 25 GB (requires caution)

Recommended cleanup approach:

1. **Use Mole for safe batch cleanup** (45 GB)
   - Open Mole
   - Select "System Caches"
   - Click "Clean"
   - This will clear ~/Library/Caches safely

2. **Use scripts for large file review** (38 GB)
   - I found 20 large files >100MB
   - Let me show you the list
   - We'll use safe_delete.py to delete selected files

3. **Manual review for app remnants** (8 GB)
   - 5 folders for possibly uninstalled apps
   - Please verify these apps are truly gone:
     - Adobe Creative Cloud (3 GB)
     - Old Xcode version (2 GB)
     - ...

4. **Manual Docker cleanup** (25 GB)
   - Requires technical review
   - I'll guide you through checking volumes

Shall we proceed with step 1 using Mole?

Mole Feature Mapping

Map Mole's features to our script capabilities:

Mole Feature	Script Equivalent	Use Case
System Caches	analyze_caches.py --user-only	Quick cache cleanup
Application Caches	analyze_caches.py	Per-app cache analysis
Large Files	analyze_large_files.py	Find space hogs
Trash	N/A (Finder)	Empty trash
Duplicate Files	Manual fdupes	Find duplicates

Mole's advantages:

• Visual representation
• One-click cleanup
• Native macOS integration

Scripts' advantages:

• Developer-specific tools (Docker, npm, pip)
• Application remnant detection
• Detailed categorization and safety notes
• Batch operations with confirmation

Coordinated Cleanup Strategy

For Non-Technical Users

1. Install Mole - Primary cleanup tool
2. Keep scripts - For occasional deep analysis
3. Workflow:
   • Monthly: Run analyze_caches.py to see what's using space
   • Use Mole to execute cleanup
   • Special cases: Use scripts

For Technical Users / Developers

1. Keep both - Mole for quick cleanup, scripts for precision
2. Workflow:
   • Weekly: Mole for routine cache cleanup
   • Monthly: Full script analysis for deep cleaning
   • As needed: Script-based cleanup for dev environment

For Power Users

1. Scripts only - Full control and automation
2. Workflow:
   • Schedule analysis scripts with cron/launchd
   • Review reports
   • Execute cleanup with safe_delete.py or direct commands

Limitations & Complementary Use

What Mole Does Well

✅ Visual disk usage analysis ✅ Safe cache cleanup ✅ User-friendly interface ✅ Quick routine maintenance

What Mole Doesn't Do (Use Scripts For)

❌ Docker cleanup ❌ Homebrew cache (command-line only) ❌ npm/pip cache ❌ Application remnant detection with confidence levels ❌ Large .git directory detection ❌ Development environment analysis

Recommended Approach

Use Mole for: 80% of routine cleanup needs Use Scripts for: 20% of specialized/technical cleanup needs

Troubleshooting

Mole Not Opening

# Check if Mole is installed
ls -l /Applications/Mole.app

# Try opening from command line (see error messages)
open -a Mole

# If not installed
echo "Download from: https://github.com/tw93/Mole/releases"

Mole Shows Different Numbers than Scripts

Explanation:

• Mole uses different calculation methods
• Scripts use du command (more accurate for directory sizes)
• Both are valid, differences typically <5%

Not a problem: Use Mole's numbers for decisions

Mole Can't Delete Some Caches

Reason: Permission issues (some caches are protected)

Solution:

1. Use scripts with sudo for system caches
2. Or manually delete in Finder with authentication

Summary

Best Practice: Use both tools

• Mole: Visual cleanup, routine maintenance, user-friendly
• Scripts: Deep analysis, developer tools, precise control

Workflow:

1. Analyze with scripts (comprehensive report)
2. Execute with Mole (safe and visual) OR scripts (precise and technical)
3. Maintain with Mole (weekly/monthly routine)

This combination provides the best user experience for macOS cleanup.