OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add reason-machines/trending-skills --skill mole-mac-cleaner
Deep clean and optimize your Mac using the Mole CLI tool
npx skills add reason-machines/trending-skills --skill mole-mac-cleaner
Skill by ara.so — Daily 2026 Skills collection.
Mole (mo) is an all-in-one macOS maintenance CLI that combines deep cleaning, smart app uninstallation, disk analysis, system optimization, live monitoring, and project artifact purging into a single binary.
Always dry-run destructive commands first:
mo clean — Deep CleanupCleans user app caches, browser caches (Chrome, Safari, Firefox), developer tool caches (Xcode, Node.js, npm), system logs, temp files, app-specific caches (Spotify, Dropbox, Slack), and Trash.
Whitelist config lives at ~/.config/mole/. Edit it to protect paths you want to keep.
mo uninstall — Smart App RemovalFinds apps, shows size and last-used date, then removes the app bundle plus all related files:
mo optimize — System RefreshOptimizations include:
mo analyze — Disk ExplorerJSON output example:
Navigator shortcuts inside mo analyze:
| Key | Action |
|---|---|
↑↓ or j/k | Navigate list |
←→ or h/l | Go back / Enter directory |
O | Open in Finder |
F | Reveal in Finder |
⌫ | Move to Trash (via Finder, safer than direct delete) |
L | Show large files |
Q | Quit |
mo status — Live DashboardJSON output example:
Shortcuts inside mo status: k toggles the cat mascot, q quits.
mo purge — Project Artifact CleanupScans for node_modules, target, build, dist, venv, and similar directories. Projects newer than 7 days are unselected by default.
Configure custom scan paths (~/.config/mole/purge_paths):
When this file exists, Mole uses only those paths. Otherwise it defaults to ~/Projects, ~/GitHub, ~/dev.
Install
fdfor faster scanning:brew install fd
mo installer — Installer File CleanupAll config lives in ~/.config/mole/:
| File | Purpose |
|---|---|
purge_paths | Custom directories for mo purge to scan |
operations.log | Log of all file operations |
Disable operation logging:
mo analyze moves files to Trash via Finder (recoverable) instead of direct deletion — prefer it for ad hoc cleanupclean, uninstall, purge, installer, and remove are permanently destructive — always --dry-run first~/.config/mole/operations.log — disable with MO_NO_OPLOG=1| Problem | Solution |
|---|---|
mo: command not found | Run brew install mole or re-run install script; check $PATH |
| Purge scan is slow | Install fd: brew install fd |
| External drives not appearing in analyze | Run mo analyze /Volumes explicitly |
| Want to protect a cache from being cleaned | Run mo clean --whitelist to add it |
| Need to exclude an optimization step | Run mo optimize --whitelist |
| Script getting interactive prompts | Use --dry-run flag; check for MO_NO_OPLOG=1 env var |
| Nightly update not working | Nightly updates (--nightly) only work with script install, not Homebrew |
mo # Interactive menu (arrow keys or vim h/j/k/l)
mo clean # Deep system cache + browser + dev tool cleanup
mo uninstall # Remove apps plus all hidden remnants
mo optimize # Rebuild caches, reset network, refresh Finder/Dock
mo analyze # Visual disk space explorer
mo status # Live real-time system health dashboard
mo purge # Remove project build artifacts (node_modules, target, dist)
mo installer # Find and remove installer .dmg/.pkg files
mo touchid # Configure Touch ID for sudo
mo completion # Set up shell tab completion
mo update # Update Mole
mo update --nightly # Update to latest unreleased build (script install only)
mo remove # Uninstall Mole itself
mo --help
mo --versionmo clean --dry-run
mo uninstall --dry-run
mo purge --dry-run
# Combine with debug for detailed output
mo clean --dry-run --debug
mo optimize --dry-run --debugmo clean # Interactive cleanup
mo clean --dry-run # Preview what would be removed
mo clean --whitelist # Manage protected caches (exclude from cleanup)mo uninstall # Interactive multi-select list
mo uninstall --dry-run # Preview removalsmo optimize # Run all optimizations
mo optimize --dry-run # Preview
mo optimize --whitelist # Exclude specific optimizationsmo analyze # Analyze home directory (skips /Volumes by default)
mo analyze ~/Downloads # Analyze specific path
mo analyze /Volumes # Include external drives explicitly
# Machine-readable output for scripting
mo analyze --json ~/Documents{
"path": "/Users/you/Documents",
"entries": [
{ "name": "Library", "path": "...", "size": 80939438080, "is_dir": true }
],
"total_size": 168393441280,
"total_files": 42187
}mo status # Real-time CPU, GPU, memory, disk, network, processes
mo status --json # JSON output for scripting
mo status | jq '.health_score' # Auto-detects pipe → outputs JSON{
"host": "MacBook-Pro",
"health_score": 92,
"cpu": { "usage": 45.2, "logical_cpu": 8 },
"memory": { "total": 25769803776, "used": 15049334784, "used_percent": 58.4 },
"disks": [],
"uptime": "3d 12h 45m"
}mo purge # Interactive multi-select
mo purge --dry-run # Preview
mo purge --paths # Configure custom scan directories~/Documents/MyProjects
~/Work/ClientA
~/Work/ClientBmo installer # Find .dmg/.pkg files in Downloads, Desktop, Homebrew cache, iCloud, Mail
mo installer --dry-run # Preview removalsexport MO_NO_OPLOG=1
mo cleanmo completion # Interactive setup for bash/zsh/fishmo touchid # Enable Touch ID authentication for sudo commands
mo touchid enable --dry-run#!/bin/bash
health=$(mo status --json | jq -r '.health_score')
if [ "$health" -lt 70 ]; then
echo "Health score low: $health — running cleanup"
mo clean --dry-run # swap to `mo clean` when ready
fimo analyze --json ~/Downloads | jq '.entries | sort_by(-.size) | .[0:5] | .[] | {name, size_gb: (.size / 1073741824 | . * 100 | round / 100)}'#!/bin/bash
# Non-interactive purge of build artifacts after CI
MO_NO_OPLOG=1 mo purge --dry-run # always preview first in scriptscurl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash
# Then bind `mo clean`, `mo status`, `mo analyze` as script commands in Raycastmo update # Update to latest stable
mo update --nightly # Update to latest main (script install only)
mo remove # Uninstall Mole completely
mo remove --dry-run # Preview what remove would delete