## Features at a Glance
- ๐ฆ **Deep System Cleanup** - Remove hidden caches, logs, and temp files in one sweep
- ๐ฆ **Thorough Uninstall** - 22+ locations cleaned vs 1 standard, beats CleanMyMac/Lemon
- ๐ **Interactive Disk Analyzer** - Navigate folders like a file manager, find and delete large files instantly
- โก๏ธ **Fast & Lightweight** - Terminal-based, zero bloat, arrow-key navigation with pagination
- ๐งน **Massive Space Recovery** - Reclaim 100GB+ of wasted disk space
## Quick Start
**Install:**
```bash
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash
```
Or via Homebrew:
```bash
brew install tw93/tap/mole
```
**Run:**
```bash
mole # Interactive menu
mole clean # System cleanup
mole clean --dry-run # Preview mode
mole uninstall # Uninstall apps
mole analyze # Disk analyzer
mole update # Update Mole
mole --help # Show help
```
> ๐ก New to terminal? Check [ๅฐ็ฝไฝฟ็จๆๅ](./GUIDE.md) ยท Homebrew users: `brew upgrade mole` to update
> โ ๏ธ **Recommended:** Always run `mole clean --dry-run` first to preview changes before cleanup
## Features
### ๐งน Deep System Cleanup
```bash
$ mole clean
โถ System essentials
โ User app cache (45.2GB) # Caches, logs, trash 20-50GB typical
โ User app logs (2.1GB)
โ Trash (12.3GB)
โถ Browser cleanup # Chrome, Safari, Arc 5-15GB typical
โ Chrome cache (8.4GB)
โ Safari cache (2.1GB)
โถ Developer tools # npm, Docker, Xcode 15-40GB typical
โ Xcode derived data (9.1GB)
โ Node.js cache (14.2GB)
โถ Others # Cloud, Office, Media 10-40GB typical
โ Dropbox cache (5.2GB)
โ Spotify cache (3.1GB)
====================================================================
๐ CLEANUP COMPLETE!
๐พ Space freed: 95.50GB | Free space now: 223.5GB
====================================================================
```
**Protect important files:**
```bash
# View default whitelist (Playwright browsers, HuggingFace models, etc.)
mole clean --whitelist
# Add custom protection
echo '~/my-important-cache/*' >> ~/.config/mole/whitelist
```
### ๐๏ธ Smart App Uninstaller
```bash
$ mole uninstall
๐๏ธ Select Apps to Remove
โโโโโโโโโโโโโโโโโโโโโโโโโโโ
โถ โ Adobe Creative Cloud (12.4G) | Old
โ WeChat (2.1G) | Recent
โ Final Cut Pro (3.8G) | Recent
๐๏ธ Uninstalling: Adobe Creative Cloud
โ Removed application # /Applications/
โ Cleaned 52 related files # ~/Library/ across 12 locations
- Support files & caches # Application Support, Caches
- Preferences & logs # Preferences, Logs
- WebKit storage & cookies # WebKit, HTTPStorages
- Extensions & plugins # Internet Plug-Ins, Services
- System files with sudo # /Library/, Launch daemons
====================================================================
๐ UNINSTALLATION COMPLETE!
Space freed: 12.8GB
====================================================================
```
### ๐ Disk Space Analyzer
```bash
$ mole analyze
๐ Analyzing: /Users/tw93
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Total: 156.8GB
โโ ๐ Library 45.2GB
โ โโ ๐ Caches 28.4GB
โ โโ ๐ Application Support 16.8GB
โโ ๐ Downloads 32.6GB
โ โโ ๐ Xcode-14.3.1.dmg 12.3GB
โ โโ ๐ backup_2023.zip 8.6GB
โ โโ ๐ฆ old_projects.tar.gz 5.2GB
โโ ๐ Movies 28.9GB
โ โโ ๐ vacation_2023.mov 15.4GB
โ โโ ๐ screencast_raw.mp4 8.8GB
โโ ๐ Documents 18.4GB
โโ ๐ Desktop 12.7GB
๐ก Navigate folders to find large files, press Delete key to remove
```
## FAQ
1. **Will Mole delete important files?** - No. Mole has built-in protection for:
- System-critical files like Input Methods, Dock, and System Preferences
- User data from IDEs like JetBrains DataGrip and VS Code, plus database tools
- License data from paid apps like 1Password and Adobe products
- Large downloaded caches like Playwright browsers and HuggingFace models
- App settings are only removed when you explicitly uninstall the app
2. **Can I undo cleanup operations?** - Cache files are safe to delete and will regenerate automatically. For important data protection, use the whitelist feature via `mole clean --whitelist`.
3. **How often should I run cleanup?** - Once a month is sufficient. Run when disk space is low.
4. **Is it safe to use?** - Yes. **Always run `mole clean --dry-run` first** to preview what will be deleted before any action.
## Support
- โญ๏ธ **Star this repo** if Mole helped you recover disk space
- ๐ฌ **Share with friends** who need to clean their Macs
- ๐ **Report issues** via [GitHub Issues](https://github.com/tw93/mole/issues)
- ๐ฑ I have two cats, feed them canned food if you'd like
## License
MIT License - feel free to enjoy and participate in open source.
