Mole

๐Ÿน Clean, uninstall, analyze, optimize, and monitor your Mac from the terminal.

Stars Version License Commits Twitter Telegram

Mole - 95.50GB freed

> ๐Ÿ’ก The CLI is free and open source. Prefer a native Mac app? [Mole for Mac](https://mole.fit) adds visual cleanup review, app updates, uninstall, maintenance, disk maps, live status, and a menu bar HUD. One license covers 2 Macs, with lifetime updates and a 14-day refund. ## Features - **All-in-one toolkit**: Combines CleanMyMac, AppCleaner, DaisyDisk, and iStat Menus in a **single binary** - **Deep cleaning**: Removes caches, logs, browser leftovers, and orphaned app data to **reclaim gigabytes of space** - **Smart uninstaller**: Removes apps plus launch agents, preferences, and **hidden remnants** - **Disk insights**: Visualizes usage, finds large files, **rebuilds caches**, and refreshes system services - **Live monitoring**: Shows real-time CPU, GPU, memory, disk, and network stats ## Quick Start **Install via Homebrew** ```bash brew install mole ``` Homebrew follows Homebrew's supported macOS tiers. Use macOS 14 or later for the Homebrew path; older macOS versions should use the script installer below on a best-effort basis. **Or via script** ```bash # Optional args: -s latest for main branch code, -s 1.17.0 for specific version curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash ``` > Note: Mole is built for macOS. An experimental Windows version is available in the [windows branch](https://github.com/tw93/Mole/tree/windows) for early adopters. **Run** ```bash mo # Interactive menu mo clean # Deep cleanup + already-uninstalled app leftovers mo uninstall # Remove installed apps + their leftovers mo optimize # Refresh caches & services mo analyze # Visual disk explorer (or 'mo analyse') mo status # Live system health dashboard mo purge # Clean project build artifacts mo installer # Find and remove installer 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 main build, script install only mo remove # Remove Mole from system mo --help # Show help mo --version # Show installed version ``` **Preview safely** ```bash mo clean --dry-run mo uninstall --dry-run mo history mo history --json mo purge --dry-run # Also works with: optimize, installer, remove, completion, touchid enable mo clean --dry-run --debug # Preview + detailed logs mo optimize --whitelist # Manage protected optimization rules mo clean --whitelist # Manage protected caches mo purge --paths # Configure project scan directories mo analyze /Volumes # Analyze external drives only ``` ## Security & Safety Design Mole is a local system maintenance tool, and some commands can perform destructive local operations. Mole uses safety-first defaults: path validation, protected-directory rules, conservative cleanup boundaries, and explicit confirmation for higher-risk actions. When risk or uncertainty is high, Mole skips, refuses, or requires stronger confirmation rather than broadening deletion scope. `mo analyze` is safer for ad hoc cleanup because it moves files to Trash through Finder instead of deleting them directly. Review [SECURITY.md](SECURITY.md) and [SECURITY_AUDIT.md](SECURITY_AUDIT.md) for reporting guidance, safety boundaries, and current limitations. ## Tips - Video tutorial: Watch the [Mole tutorial video](https://www.youtube.com/watch?v=UEe9-w4CcQ0), thanks to PAPAYA ้›ป่…ฆๆ•™ๅฎค. - Safety and logs: `clean`, `uninstall`, `purge`, `installer`, and `remove` are destructive. Review with `--dry-run` first, and add `--debug` when needed. File operations are logged to `~/Library/Logs/mole/operations.log` and can be reviewed with `mo history`. Disable with `MO_NO_OPLOG=1`. Review [SECURITY.md](SECURITY.md) and [SECURITY_AUDIT.md](SECURITY_AUDIT.md). - App leftovers: use `mo clean` when the app is already uninstalled, and `mo uninstall` when the app is still installed. - Navigation: Mole supports arrow keys and Vim bindings `h/j/k/l`. ## Features in Detail ### Deep System Cleanup ```bash $ mo clean Scanning cache directories... โœ“ User app cache 45.2GB โœ“ Browser cache (Chrome, Safari, Firefox) 10.5GB โœ“ Developer tools (Xcode, Node.js, npm) 23.3GB โœ“ System logs and temp files 3.8GB โœ“ App-specific cache (Spotify, Dropbox, Slack) 8.4GB โœ“ Trash 12.3GB ==================================================================== Space freed: 95.5GB | Free space now: 223.5GB ==================================================================== ``` Note: In `mo clean` -> Developer tools, Mole removes unused CoreSimulator `Volumes/Cryptex` entries and skips `IN_USE` items. ### Smart App Uninstaller ```bash $ mo uninstall Select Apps to Remove โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• โ–ถ โ˜‘ Photoshop 2024 (4.2G) | Old โ˜ IntelliJ IDEA (2.8G) | Recent โ˜ Premiere Pro (3.4G) | Recent Uninstalling: Photoshop 2024 โœ“ Removed application โœ“ Cleaned 52 related files across 12 locations - Application Support, Caches, Preferences - Logs, WebKit storage, Cookies - Extensions, Plugins, Launch daemons Note: On macOS 15 and later, Local Network permission entries can outlive app removal. Mole warns when an uninstalled app declares Local Network usage, but it does not auto-reset `/Volumes/Data/Library/Preferences/com.apple.networkextension*.plist` because that reset is global and requires Recovery mode. ==================================================================== Space freed: 12.8GB ==================================================================== ``` ### System Optimization ```bash $ mo optimize System: 5/32 GB RAM | 333/460 GB Disk (72%) | Uptime 6d โœ“ Rebuild system databases and clear caches โœ“ Reset network services โœ“ Refresh Finder and Dock โœ“ Clean diagnostic and crash logs โœ“ Remove swap files and restart dynamic pager โœ“ Rebuild launch services and spotlight index ==================================================================== System optimization completed ==================================================================== Use `mo optimize --whitelist` to exclude specific optimizations. Path patterns work too, so you can keep a long-lived mounted disk image around (for example `/Volumes/mail`) without it showing up as a detach candidate. ``` ### Disk Space Analyzer > Note: By default, Mole skips external drives under `/Volumes` for faster startup. To inspect them, run `mo analyze /Volumes` or a specific mount path. ```bash $ mo analyze Analyze Disk ~/Documents | Total: 156.8GB โ–ถ 1. โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 48.2% | ๐Ÿ“ Library 75.4GB >6mo 2. โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 22.1% | ๐Ÿ“ Downloads 34.6GB 3. โ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 14.3% | ๐Ÿ“ Movies 22.4GB 4. โ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 10.8% | ๐Ÿ“ Documents 16.9GB 5. โ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 5.2% | ๐Ÿ“„ backup_2023.zip 8.2GB โ†‘โ†“โ†โ†’ Navigate | O Open | F Show | โŒซ Delete | L Large files | Q Quit ``` ### Live System Status Real-time dashboard with health score, hardware info, and performance metrics. ```bash $ mo status Mole Status Health โ— 92 MacBook Pro ยท M4 Pro ยท 32GB ยท macOS 14.5 โš™ CPU โ–ฆ Memory Total โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 45.2% Used โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 58.4% Load 0.82 / 1.05 / 1.23 (8 cores) Total 14.2 / 24.0 GB Core 1 โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘ 78.3% Free โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 41.6% Core 2 โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 62.1% Avail 9.8 GB โ–ค Disk โšก Power Used โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 67.2% Level โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 100% Free 156.3 GB Status Charged Read โ–ฎโ–ฏโ–ฏโ–ฏโ–ฏ 2.1 MB/s Health Normal ยท 423 cycles Write โ–ฎโ–ฎโ–ฎโ–ฏโ–ฏ 18.3 MB/s Temp 58ยฐC ยท 1200 RPM โ‡… Network โ–ถ Processes Down โ–โ–โ–ˆโ–‚โ–โ–โ–โ–โ–โ–โ–โ–โ–‡โ–†โ–…โ–‚ 0.54 MB/s Code โ–ฎโ–ฎโ–ฎโ–ฎโ–ฏ 42.1% Up โ–„โ–„โ–„โ–ƒโ–ƒโ–ƒโ–„โ–†โ–†โ–‡โ–ˆโ–โ–โ–โ–โ– 0.02 MB/s Chrome โ–ฎโ–ฎโ–ฎโ–ฏโ–ฏ 28.3% Proxy HTTP ยท 192.168.1.100 Terminal โ–ฎโ–ฏโ–ฏโ–ฏโ–ฏ 12.5% ``` Health score is based on CPU, memory, disk, temperature, and I/O load, with color-coded ranges. Shortcuts: In `mo status`, press `k` to toggle the cat and save the preference, and `q` to quit. When enabled, `mo status` shows a read-only alert banner for processes that stay above the configured CPU threshold for a sustained window. Use `--proc-cpu-threshold`, `--proc-cpu-window`, or `--proc-cpu-alerts=false` to tune or disable it. #### Machine-Readable Output Both `mo analyze` and `mo status` support a `--json` flag for scripting and automation. `mo status` also auto-detects when its output is piped (not a terminal) and switches to JSON automatically. ```bash # Disk analysis as JSON $ mo analyze --json ~/Documents { "path": "/Users/you/Documents", "overview": false, "entries": [ { "name": "Library", "path": "...", "size": 80939438080, "is_dir": true }, ... ], "large_files": [ { "name": "backup.zip", "path": "...", "size": 8796093022 } ], "total_size": 168393441280, "total_files": 42187 } # System status as JSON $ mo status --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", ... } # Auto-detected JSON when piped $ mo status | jq '.health_score' 92 ``` ### Project Artifact Purge Clean old build artifacts such as `node_modules`, `target`, `.build`, `build`, and `dist` to free up disk space. ```bash mo purge Select Categories to Clean - 18.5GB (8 selected) โžค โ— my-react-app 3.2GB | node_modules โ— old-project 2.8GB | node_modules โ— rust-app 4.1GB | target โ— next-blog 1.9GB | node_modules โ—‹ current-work 856MB | node_modules | Recent โ— django-api 2.3GB | venv โ— vue-dashboard 1.7GB | node_modules โ— backend-service 2.5GB | node_modules ``` > Note: We recommend installing `fd` on macOS. > `brew install fd` > Safety: This permanently deletes selected artifacts. Review carefully before confirming. Projects newer than 7 days are marked and unselected by default.
Custom Scan Paths Run `mo purge --paths` to configure scan directories, or edit `~/.config/mole/purge_paths` directly: ```shell ~/Documents/MyProjects ~/Work/ClientA ~/Work/ClientB ``` When custom paths are configured, Mole scans only those directories. Otherwise, it uses defaults like `~/Projects`, `~/GitHub`, and `~/dev`.
### Installer Cleanup Find and remove large installer files across Downloads, Desktop, Homebrew caches, iCloud, and Mail. Each file is labeled by source. ```bash mo installer Select Installers to Remove - 3.8GB (5 selected) โžค โ— Photoshop_2024.dmg 1.2GB | Downloads โ— IntelliJ_IDEA.dmg 850.6MB | Downloads โ— Illustrator_Setup.pkg 920.4MB | Downloads โ— PyCharm_Pro.dmg 640.5MB | Homebrew โ— Acrobat_Reader.dmg 220.4MB | Downloads โ—‹ AppCode_Legacy.zip 410.6MB | Downloads ``` ## Quick Launchers Launch Mole commands from Raycast or Alfred: ```bash curl -fsSL https://raw.githubusercontent.com/tw93/Mole/main/scripts/setup-quick-launchers.sh | bash ``` Adds 5 commands: `Mole Clean`, `Mole Uninstall`, `Mole Optimize`, `Mole Analyze`, `Mole Status`. ### Raycast Setup After running the script, complete these steps in Raycast: 1. Open Raycast Settings (โŒ˜ + ,) 2. Go to **Extensions** โ†’ **Script Commands** 3. Click **"Add Script Directory"** (or **"+"**) 4. Add path: `~/Library/Application Support/Raycast/script-commands` 5. Search in Raycast for: **"Reload Script Directories"** and run it 6. Done! Search for `Mole Clean` or `clean`, `Mole Optimize`, or `Mole Status` to use the commands > **Note**: The script creates the commands, but Raycast still requires a one-time manual script directory setup. ### Terminal Detection Mole auto-detects your terminal app. iTerm2 has known compatibility issues. We highly recommend [Kaku](https://github.com/tw93/Kaku). Other good options are Alacritty, kitty, WezTerm, Ghostty, and Warp. To override, set `MO_LAUNCHER_APP=`. ## Community Love Thanks to everyone who helped build Mole. Go follow them. โค๏ธ

Real feedback from users who shared Mole on X. Community feedback on Mole ## Support - If Mole helped you, [share it](https://twitter.com/intent/tweet?url=https://github.com/tw93/Mole&text=Mole%20-%20Deep%20clean%20and%20optimize%20your%20Mac.) with friends or give it a star. - Got ideas or bugs? Open an issue or PR, feel free to contribute your best AI model. - I have two cats, TangYuan and Coke. If you think Mole delights your life, you can feed them canned food ๐Ÿฅฉ. - Getting [Mole for Mac](https://mole.fit) is also the most direct way to support Mole's development.
Thanks to everyone who has fed them ๐Ÿฅฉ
## License Mole is open source under GPL-3.0, see [LICENSE](LICENSE). A version you modify and share stays open under the same license, and if you fork Mole into your own product, to avoid confusion please give it a different name and credit Mole as the source. [Mole for Mac](https://mole.fit) is a separate, proprietary app, and Mole is here for the long run.