https://github.com/tw93/mole
๐น Deep clean and optimize your Mac.
https://github.com/tw93/mole
analyzer appcleaner clean cleaner cleaner-cli cleaner-script command-line daisydisk istat mac macos optimize sensei shell uninstall
Last synced: 4 days ago
JSON representation
๐น Deep clean and optimize your Mac.
- Host: GitHub
- URL: https://github.com/tw93/mole
- Owner: tw93
- License: mit
- Created: 2025-09-23T06:38:40.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-05-21T03:44:20.000Z (7 days ago)
- Last Synced: 2026-05-21T09:56:22.003Z (6 days ago)
- Topics: analyzer, appcleaner, clean, cleaner, cleaner-cli, cleaner-script, command-line, daisydisk, istat, mac, macos, optimize, sensei, shell, uninstall
- Language: Shell
- Homepage: https://mole.fit
- Size: 226 MB
- Stars: 52,213
- Watchers: 132
- Forks: 1,649
- Open Issues: 31
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
Mole
Deep clean and optimize your Mac.
> The CLI stays free and open source. Prefer a GUI? Try [Mole Mac App](https://mole.fit), $9 lifetime, code **MOLEMAC** for 20% off through May 23.
## 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
```
**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 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`. 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.
```
### 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.
## 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 ๐ฅฉ.
## License
MIT License. Feel free to use Mole and contribute.