Release v1.21.0: Add macos-cleaner skill
- Add macos-cleaner v1.0.0 - Intelligent macOS disk space recovery - Safety-first philosophy with risk categorization (Safe/Caution/Keep) - Smart analysis: caches, app remnants, large files, dev environments - Interactive cleanup with explicit user confirmation - Bundled scripts: analyze_caches, analyze_dev_env, analyze_large_files, find_app_remnants, safe_delete, cleanup_report - Comprehensive references: cleanup_targets, mole_integration, safety_rules - Update marketplace to v1.21.0 - Update all documentation (README.md, README.zh-CN.md, CHANGELOG.md, CLAUDE.md) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
daymade
304
macos-cleaner/references/mole_integration.md
Normal file
304
macos-cleaner/references/mole_integration.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# Mole Integration Guide
|
||||
|
||||
How to integrate [Mole](https://github.com/tw93/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
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```markdown
|
||||
🔍 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
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
Reference in New Issue
Block a user