Release v1.21.1: Update macos-cleaner to v1.1.0
Major improvements based on real-world usage experience: - Add "Value Over Vanity" principle - prioritize identifying truly useless items over maximizing cleanup numbers - Add "Network Environment Awareness" - consider slow internet when recommending cache deletion - Add "Impact Analysis Required" - every recommendation must explain consequences - Add comprehensive "Anti-Patterns" section documenting what NOT to delete - Add "Multi-Layer Deep Exploration" guide with complete tmux + Mole TUI navigation workflow - Add "High-Quality Report Template" with proven 3-tier classification (🟢/🟡/🔴) - Add "Report Quality Checklist" for verification before presenting findings - Add explicit prohibition of `docker volume prune -f` - Update safety principles to emphasize cache value over cleanup metrics Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
daymade
@@ -1,4 +1,4 @@
|
||||
Security scan passed
|
||||
Scanned at: 2026-01-11T15:33:50.497864
|
||||
Scanned at: 2026-01-11T17:48:10.512079
|
||||
Tool: gitleaks + pattern-based validation
|
||||
Content hash: 837b8b7dfa3a728295649b608acaba00d7eb2b1fbbe02a35f5c8e0ffc8c2e361
|
||||
Content hash: de94268166b88b2b704930f641a401a1eddcf2ea957ca6185533203b9e13fb04
|
||||
|
||||
@@ -13,11 +13,21 @@ Intelligently analyze macOS disk usage and provide actionable cleanup recommenda
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Analyze First, Act Second**: Never delete files without explicit user confirmation
|
||||
2. **Transparency**: Explain what each file/directory is and why it's safe (or unsafe) to delete
|
||||
3. **Interactive Decision Making**: Present findings in human-readable format, let users decide
|
||||
4. **Conservative Defaults**: When in doubt, don't delete
|
||||
5. **Backup Suggestions**: Recommend Time Machine backup before major cleanups
|
||||
1. **Safety First, Never Bypass**: NEVER execute dangerous commands (`rm -rf`, `mo clean`, etc.) without explicit user confirmation. No shortcuts, no workarounds.
|
||||
2. **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.
|
||||
3. **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.
|
||||
4. **Impact Analysis Required**: Every cleanup recommendation MUST include "what happens if deleted" column. Never just list items without explaining consequences.
|
||||
5. **Patience Over Speed**: Disk scans can take 5-10 minutes. NEVER interrupt or skip slow operations. Report progress to user regularly.
|
||||
6. **User Executes Cleanup**: After analysis, provide the cleanup command for the user to run themselves. Do NOT auto-execute cleanup.
|
||||
7. **Conservative Defaults**: When in doubt, don't delete. Err on the side of caution.
|
||||
|
||||
**ABSOLUTE PROHIBITIONS:**
|
||||
- ❌ NEVER run `rm -rf` on user directories automatically
|
||||
- ❌ NEVER run `mo clean` without dry-run preview first
|
||||
- ❌ NEVER use `docker volume prune -f` or `docker system prune -a --volumes`
|
||||
- ❌ NEVER skip analysis steps to save time
|
||||
- ❌ NEVER append `--help` to Mole commands (except `mo --help`)
|
||||
- ❌ NEVER recommend deleting useful caches just to inflate cleanup numbers
|
||||
|
||||
## Workflow Decision Tree
|
||||
|
||||
@@ -42,41 +52,124 @@ Immediate Deep Analysis
|
||||
Verify Results
|
||||
```
|
||||
|
||||
## Step 1: Quick Diagnosis
|
||||
## Step 1: Quick Diagnosis with Mole
|
||||
|
||||
Start with a rapid assessment to understand the scope:
|
||||
**Primary tool**: Use Mole for disk analysis. It provides comprehensive, categorized results.
|
||||
|
||||
### 1.1 Pre-flight Checks
|
||||
|
||||
```bash
|
||||
# Check available disk space
|
||||
df -h /
|
||||
# Check Mole installation and version
|
||||
which mo && mo --version
|
||||
|
||||
# Find top 10 largest directories in home folder
|
||||
du -h -d 1 ~ | sort -hr | head -n 10
|
||||
# If not installed
|
||||
brew install tw93/tap/mole
|
||||
|
||||
# Quick check for common space hogs
|
||||
du -sh ~/Library/Caches ~/Library/Logs ~/Downloads ~/.Trash 2>/dev/null
|
||||
# Check for updates (Mole updates frequently)
|
||||
brew info tw93/tap/mole | head -5
|
||||
|
||||
# Upgrade if outdated
|
||||
brew upgrade tw93/tap/mole
|
||||
```
|
||||
|
||||
**Present findings in this format:**
|
||||
### 1.2 Choose Analysis Method
|
||||
|
||||
**IMPORTANT**: Use `mo analyze` as the primary analysis tool, NOT `mo clean --dry-run`.
|
||||
|
||||
| Command | Purpose | Use When |
|
||||
|---------|---------|----------|
|
||||
| `mo analyze` | Interactive disk usage explorer (TUI tree view) | **PRIMARY**: Understanding what's consuming space |
|
||||
| `mo clean --dry-run` | Preview cleanup categories | **SECONDARY**: Only after `mo analyze` to see cleanup preview |
|
||||
|
||||
**Why prefer `mo analyze`:**
|
||||
- Dedicated disk analysis tool with interactive tree navigation
|
||||
- Allows drilling down into specific directories
|
||||
- Shows actual disk usage breakdown, not just cleanup categories
|
||||
- More informative for understanding storage consumption
|
||||
|
||||
### 1.3 Run Analysis via tmux
|
||||
|
||||
**IMPORTANT**: Mole requires TTY. Always use tmux from Claude Code.
|
||||
|
||||
**CRITICAL TIMING NOTE**: Home directory scans are SLOW (5-10 minutes or longer for large directories). Inform user upfront and wait patiently.
|
||||
|
||||
```bash
|
||||
# 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)**
|
||||
```bash
|
||||
# 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 Space Analysis
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Total: 500 GB
|
||||
Used: 450 GB (90%)
|
||||
Available: 50 GB (10%)
|
||||
📊 Disk Analysis in Progress...
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
⏱️ Elapsed: 2 minutes
|
||||
|
||||
🔍 Top Space Consumers:
|
||||
1. ~/Library/Caches 45 GB
|
||||
2. ~/Downloads 38 GB
|
||||
3. ~/Library/Application Support 25 GB
|
||||
4. ~/.Trash 12 GB
|
||||
5. ~/Library/Logs 8 GB
|
||||
Current status:
|
||||
✅ Applications: 49.5 GB (complete)
|
||||
✅ System Library: 10.3 GB (complete)
|
||||
⏳ Home: scanning... (this may take 5-10 minutes)
|
||||
⏳ App Library: pending
|
||||
|
||||
⚡ Quick Win Opportunities:
|
||||
- Empty Trash: ~12 GB
|
||||
- Clear Downloads: ~38 GB (requires user review)
|
||||
- System Caches: ~45 GB (mostly safe to clear)
|
||||
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
|
||||
@@ -192,48 +285,474 @@ Total potential: 9 GB
|
||||
|
||||
**Cleanup commands (require confirmation):**
|
||||
```bash
|
||||
# Docker cleanup
|
||||
docker system prune -a --volumes
|
||||
|
||||
# Homebrew cleanup
|
||||
# Homebrew cleanup (safe)
|
||||
brew cleanup -s
|
||||
|
||||
# npm cache
|
||||
npm cache clean --force
|
||||
# npm _npx only (safe - temporary packages)
|
||||
rm -rf ~/.npm/_npx
|
||||
|
||||
# pip cache
|
||||
# pip cache (use with caution)
|
||||
pip cache purge
|
||||
```
|
||||
|
||||
**Safety level**: 🟢 Safe for development caches, 🟡 Caution for Docker volumes
|
||||
**Docker cleanup - SPECIAL HANDLING REQUIRED:**
|
||||
|
||||
⚠️ **NEVER use these commands:**
|
||||
```bash
|
||||
# ❌ DANGEROUS - deletes ALL volumes without confirmation
|
||||
docker volume prune -f
|
||||
docker system prune -a --volumes
|
||||
```
|
||||
|
||||
✅ **Correct approach - per-volume confirmation:**
|
||||
```bash
|
||||
# 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 3: Integration with Mole
|
||||
|
||||
**Mole** (https://github.com/tw93/Mole) is a visual macOS cleaner. Recommend it as a complementary tool for users who want GUI-based cleanup.
|
||||
**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.
|
||||
|
||||
**When to suggest Mole:**
|
||||
- User prefers visual interface over command-line
|
||||
- User wants one-click cleaning for common targets
|
||||
- Script analysis reveals complex cleanup needs
|
||||
**CRITICAL REQUIREMENTS:**
|
||||
|
||||
**How to integrate:**
|
||||
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.
|
||||
|
||||
1. **Check if Mole is installed:**
|
||||
```bash
|
||||
if [ -d "/Applications/Mole.app" ]; then
|
||||
echo "✅ Mole is installed"
|
||||
else
|
||||
echo "💡 Consider installing Mole for visual cleanup: https://github.com/tw93/Mole"
|
||||
fi
|
||||
```
|
||||
**Installation check and upgrade:**
|
||||
|
||||
2. **Coordinate workflow:**
|
||||
- Use scripts for detailed analysis and reports
|
||||
- Suggest Mole for executing approved cleanups
|
||||
- Use scripts for developer-specific cleanup (Docker, npm, etc.)
|
||||
```bash
|
||||
# Check if installed and get version
|
||||
which mo && mo --version
|
||||
|
||||
3. **Reference guide:**
|
||||
See `references/mole_integration.md` for detailed usage.
|
||||
# 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):**
|
||||
|
||||
```bash
|
||||
# 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`):**
|
||||
|
||||
| Command | Safety | Description |
|
||||
|---------|--------|-------------|
|
||||
| `mo --help` | ✅ Safe | View all commands (ONLY safe help) |
|
||||
| `mo analyze` | ✅ 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
|
||||
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
# 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)**
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
# 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
|
||||
|
||||
| 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
## 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:
|
||||
|
||||
```markdown
|
||||
## 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.
|
||||
```
|
||||
|
||||
## High-Quality Report Template
|
||||
|
||||
After multi-layer exploration, present findings using this proven template:
|
||||
|
||||
```markdown
|
||||
## 📊 磁盘空间深度分析报告
|
||||
|
||||
**分析日期**: 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 | [说明] |
|
||||
|
||||
---
|
||||
|
||||
### 推荐操作
|
||||
|
||||
**立即可执行** (无需确认):
|
||||
```bash
|
||||
# 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 项目** - 告诉我哪些项目确定不用了
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
|
||||
@@ -4,69 +4,31 @@ How to integrate [Mole](https://github.com/tw93/Mole) with the macOS Cleaner ski
|
||||
|
||||
## About Mole
|
||||
|
||||
**Mole** is a visual macOS disk cleanup tool with a native macOS interface. It provides:
|
||||
**Mole** is a command-line interface (CLI) tool for macOS disk cleanup. It provides:
|
||||
|
||||
- Visual disk usage analysis
|
||||
- One-click cleanup for common targets
|
||||
- Safe deletion with preview
|
||||
- Native macOS design
|
||||
- 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
|
||||
|
||||
## When to Recommend Mole
|
||||
## Critical: TTY Environment Required
|
||||
|
||||
Suggest Mole to users in these scenarios:
|
||||
**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.
|
||||
|
||||
### 1. User Prefers Visual Interface
|
||||
```bash
|
||||
# Create tmux session for Mole commands
|
||||
tmux new-session -d -s mole -x 120 -y 40
|
||||
|
||||
```
|
||||
User: "I prefer clicking buttons rather than running commands"
|
||||
```
|
||||
# Send command to tmux session
|
||||
tmux send-keys -t mole 'mo analyze' Enter
|
||||
|
||||
**Response**:
|
||||
```
|
||||
I recommend using Mole alongside these scripts:
|
||||
# Capture output
|
||||
tmux capture-pane -t mole -p
|
||||
|
||||
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.
|
||||
# Clean up when done
|
||||
tmux kill-session -t mole
|
||||
```
|
||||
|
||||
## Installation
|
||||
@@ -74,231 +36,407 @@ This hybrid approach gives you both convenience and precision.
|
||||
### 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
|
||||
# Check if mole command exists
|
||||
which mo && mo --version
|
||||
```
|
||||
|
||||
### Installation Methods
|
||||
Expected output:
|
||||
```
|
||||
/opt/homebrew/bin/mo
|
||||
Mole version X.Y.Z
|
||||
macOS: XX.X
|
||||
Architecture: arm64
|
||||
...
|
||||
```
|
||||
|
||||
**Method 1: Download from GitHub Releases**
|
||||
### Installation via Homebrew (Recommended)
|
||||
|
||||
```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
|
||||
brew install tw93/tap/mole
|
||||
```
|
||||
|
||||
**Method 2: Build from Source** (if user is developer)
|
||||
### 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.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tw93/Mole.git
|
||||
cd Mole
|
||||
# Follow build instructions in README
|
||||
# Check current vs latest version
|
||||
brew info tw93/tap/mole | head -5
|
||||
|
||||
# If outdated, upgrade
|
||||
brew upgrade tw93/tap/mole
|
||||
```
|
||||
|
||||
## Workflow Integration
|
||||
## Available Commands
|
||||
|
||||
### Hybrid Workflow: Scripts + Mole
|
||||
|
||||
**Best practice**: Use both tools for their strengths.
|
||||
|
||||
#### Step 1: Analysis with Scripts
|
||||
|
||||
Run comprehensive analysis:
|
||||
**CRITICAL**: Only use `mo --help` to view help. Do NOT append `--help` to other commands as it may cause unexpected behavior.
|
||||
|
||||
```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
|
||||
# View all commands (SAFE - the only help command)
|
||||
mo --help
|
||||
```
|
||||
|
||||
This gives detailed reports with safety categorization.
|
||||
Available commands from `mo --help`:
|
||||
|
||||
#### Step 2: Review Findings
|
||||
| Command | Description | Safety |
|
||||
|---------|-------------|--------|
|
||||
| `mo` | Interactive main menu | Requires TTY |
|
||||
| `mo clean` | Free up disk space | **DANGEROUS** - deletes files |
|
||||
| `mo clean --dry-run` | Preview cleanup (no deletion) | Safe |
|
||||
| `mo analyze` | Explore disk usage | Safe (read-only) |
|
||||
| `mo status` | Monitor system health | Safe (read-only) |
|
||||
| `mo uninstall` | Remove apps completely | **DANGEROUS** |
|
||||
| `mo purge` | Remove old project artifacts | **DANGEROUS** |
|
||||
| `mo optimize` | Check and maintain system | Caution required |
|
||||
| `mo installer` | Find and remove installer files | Caution required |
|
||||
|
||||
Present findings to user in readable format (see SKILL.md Step 4).
|
||||
## mo analyze vs mo clean --dry-run
|
||||
|
||||
#### Step 3: Execute Cleanup
|
||||
**CRITICAL**: These are two different tools with different purposes. Use the right tool for the job.
|
||||
|
||||
For different types of cleanup:
|
||||
### Comparison Table
|
||||
|
||||
**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
|
||||
| Aspect | `mo analyze` | `mo clean --dry-run` |
|
||||
|--------|--------------|---------------------|
|
||||
| **Primary Purpose** | Explore disk usage interactively | Preview cleanup categories |
|
||||
| **Use When** | Understanding what consumes space | Ready to see cleanup options |
|
||||
| **Interface** | Interactive TUI with tree navigation | Static list output |
|
||||
| **Navigation** | Arrow keys to drill into directories | No navigation |
|
||||
| **Detail Level** | Full directory breakdown | Only cleanup-eligible items |
|
||||
| **Recommended Order** | **Use FIRST** | Use SECOND (after analyze) |
|
||||
|
||||
**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
|
||||
### When to Use Each
|
||||
|
||||
**Option C: Manual** (for sensitive items)
|
||||
- Guide user to review in Finder
|
||||
- User deletes manually
|
||||
**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
|
||||
|
||||
### Example Integrated Session
|
||||
**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
|
||||
|
||||
```markdown
|
||||
🔍 Analysis Results
|
||||
### Workflow Recommendation
|
||||
|
||||
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?
|
||||
```
|
||||
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)
|
||||
```
|
||||
|
||||
## Mole Feature Mapping
|
||||
### Common Mistake
|
||||
|
||||
Map Mole's features to our script capabilities:
|
||||
```bash
|
||||
# ❌ 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
|
||||
|
||||
| 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 |
|
||||
# ✅ CORRECT: Start with disk analysis
|
||||
tmux send-keys -t mole 'mo analyze' Enter
|
||||
# This shows where ALL disk space is going
|
||||
```
|
||||
|
||||
**Mole's advantages**:
|
||||
- Visual representation
|
||||
- One-click cleanup
|
||||
- Native macOS integration
|
||||
### Interactive TUI Navigation (mo analyze)
|
||||
|
||||
**Scripts' advantages**:
|
||||
- Developer-specific tools (Docker, npm, pip)
|
||||
- Application remnant detection
|
||||
- Detailed categorization and safety notes
|
||||
- Batch operations with confirmation
|
||||
`mo analyze` provides an interactive tree view. Navigate using tmux key sequences:
|
||||
|
||||
## Coordinated Cleanup Strategy
|
||||
```bash
|
||||
# Start analysis
|
||||
tmux send-keys -t mole 'mo analyze' Enter
|
||||
|
||||
### For Non-Technical Users
|
||||
# Wait for scan to complete (5-10 minutes for Home directory!)
|
||||
sleep 300 # 5 minutes for large directories
|
||||
|
||||
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
|
||||
# Capture current view
|
||||
tmux capture-pane -t mole -p
|
||||
|
||||
### For Technical Users / Developers
|
||||
# Navigate down to next item
|
||||
tmux send-keys -t mole Down
|
||||
|
||||
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
|
||||
# Expand/enter selected directory
|
||||
tmux send-keys -t mole Enter
|
||||
|
||||
### For Power Users
|
||||
# Go back up
|
||||
tmux send-keys -t mole Up
|
||||
|
||||
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
|
||||
# Quit the TUI
|
||||
tmux send-keys -t mole 'q'
|
||||
```
|
||||
|
||||
## Limitations & Complementary Use
|
||||
## Safe Analysis Workflow
|
||||
|
||||
### What Mole Does Well
|
||||
### Step 1: Check Version First
|
||||
|
||||
✅ Visual disk usage analysis
|
||||
✅ Safe cache cleanup
|
||||
✅ User-friendly interface
|
||||
✅ Quick routine maintenance
|
||||
```bash
|
||||
# Always ensure latest version
|
||||
brew info tw93/tap/mole | head -3
|
||||
```
|
||||
|
||||
### What Mole Doesn't Do (Use Scripts For)
|
||||
### Step 2: Create TTY Environment
|
||||
|
||||
❌ Docker cleanup
|
||||
❌ Homebrew cache (command-line only)
|
||||
❌ npm/pip cache
|
||||
❌ Application remnant detection with confidence levels
|
||||
❌ Large .git directory detection
|
||||
❌ Development environment analysis
|
||||
```bash
|
||||
# Start tmux session
|
||||
tmux new-session -d -s mole -x 120 -y 40
|
||||
```
|
||||
|
||||
### Recommended Approach
|
||||
### Step 3: Run Analysis (Safe Commands Only)
|
||||
|
||||
**Use Mole for**: 80% of routine cleanup needs
|
||||
**Use Scripts for**: 20% of specialized/technical cleanup needs
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
**Items that should usually be KEPT:**
|
||||
| Item | Why Keep It |
|
||||
|------|-------------|
|
||||
| Xcode DerivedData | Saves 10-30 min per rebuild |
|
||||
| npm _cacache | Avoids re-downloading all packages |
|
||||
| ~/.cache/uv | Python package cache |
|
||||
| Playwright browsers | Avoids 2GB+ redownload |
|
||||
| iOS DeviceSupport | Needed for device debugging |
|
||||
| Docker stopped containers | May restart anytime |
|
||||
|
||||
**Items that are truly safe to delete:**
|
||||
| Item | Why Safe |
|
||||
|------|----------|
|
||||
| Trash | User already deleted |
|
||||
| Homebrew old versions | Replaced by newer |
|
||||
| npm _npx | Temporary executions |
|
||||
|
||||
### 1. Never Execute Dangerous Commands Automatically
|
||||
|
||||
```bash
|
||||
# ❌ 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**:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
### Mole Not Opening
|
||||
### "device not configured" Error
|
||||
|
||||
**Cause**: Command run without TTY environment.
|
||||
|
||||
**Solution**: Use tmux:
|
||||
```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"
|
||||
tmux new-session -d -s mole
|
||||
tmux send-keys -t mole 'mo status' Enter
|
||||
```
|
||||
|
||||
### Mole Shows Different Numbers than Scripts
|
||||
### Scan Stuck on "pending"
|
||||
|
||||
**Explanation**:
|
||||
- Mole uses different calculation methods
|
||||
- Scripts use `du` command (more accurate for directory sizes)
|
||||
- Both are valid, differences typically <5%
|
||||
**Cause**: Large directories take time to scan.
|
||||
|
||||
**Not a problem**: Use Mole's numbers for decisions
|
||||
**Solution**: Be patient. Home directory with many files can take 5-10 minutes. Monitor progress:
|
||||
```bash
|
||||
# Check if still scanning (spinner animation in output)
|
||||
tmux capture-pane -t mole -p | tail -10
|
||||
```
|
||||
|
||||
### Mole Can't Delete Some Caches
|
||||
### Non-Interactive Mode Auto-Executes
|
||||
|
||||
**Reason**: Permission issues (some caches are protected)
|
||||
**WARNING**: Some Mole commands may auto-execute in non-TTY environments without confirmation!
|
||||
|
||||
**Solution**: ALWAYS use tmux for ANY Mole command, even help:
|
||||
```bash
|
||||
# ❌ 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**:
|
||||
1. Use scripts with sudo for system caches
|
||||
2. Or manually delete in Finder with authentication
|
||||
```bash
|
||||
# Check versions
|
||||
brew info tw93/tap/mole
|
||||
|
||||
# Upgrade
|
||||
brew upgrade tw93/tap/mole
|
||||
```
|
||||
|
||||
## 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.
|
||||
**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
|
||||
|
||||
Reference in New Issue
Block a user