A cleanup & monitor CLI for macOS
Preview first · Trash by default · One command and you’re ready
Languages: English · 简体中文 · 繁體中文 · 日本語 · 한국어
Caches, logs, leftovers, installers, build junk… Vole finds them so you can preview, then clean. Trash by default—easy to undo if you change your mind.
Quick nav Screenshots · Features · Install · Usage · Safety · FAQ · Desktop app · About · Credits · License
Run vole in Terminal to open the interactive home menu—arrow keys to move, Enter to select.
| Feature | What you get |
|---|---|
| Clean | Find caches, logs, and leftovers—confirm, then clean |
| Uninstall | Remove apps and as much leftover data as possible |
| Optimize | Run a bounded set of safe system maintenance tasks |
| Purge | Clear bulky items like stale project build artifacts |
| Installer | Find forgotten .dmg / .pkg files on disk |
| Analyze | See which folders and large files use the most space |
| History | Review past cleanups and deletions |
| Status | Live CPU, memory, and disk health |
| Worktree | List leftover Git worktrees and move them to Trash after confirm |
Type vole in Terminal for an interactive home menu. About 540 cleanup rules are built in—no extra tools to install.
For anyone comfortable with Terminal who wants a safer Mac cleaner than “delete everything in one click.” Prefer a windowed app? See Desktop app below.
Requires macOS 12+.
Current release: v2.19.1 (Developer ID signed and notarized). Builds for Apple Silicon and Intel.
Paste the block below into Cursor, Claude Code, Codex, ChatGPT, or any coding assistant. It will install Vole for you.
Install Vole (a macOS cleanup & monitor CLI) on this Mac.
Official repo: https://github.com/wukongnotnull/vole
Requires macOS 12+. Install only — do not run clean / uninstall / optimize or any command that changes the system.
Do this in order and stop at the first success:
1. If Homebrew is available:
brew tap wukongnotnull/vole https://github.com/wukongnotnull/vole
brew install vole
2. Otherwise download the latest notarized GitHub Release tarball for this Mac
(Apple Silicon: aarch64-apple-darwin; Intel: x86_64-apple-darwin).
Install bin/vole to ~/.local/bin and copy share/vole/rules to ~/.local/share/vole/rules.
If needed, add ~/.local/bin to PATH in ~/.zshrc.
3. Do not build from source unless both of the above fail.
Then run `vole --version`, and tell me the install path and version.
Or just say: Install Vole from https://github.com/wukongnotnull/vole
brew tap wukongnotnull/vole https://github.com/wukongnotnull/vole
brew install voleThen run vole. If brew fails or the version looks wrong, use the download option below.
- Open the latest Release
- Download the archive for your chip:
- Apple Silicon (M-series):
…-aarch64-apple-darwin.tar.gz - Intel:
…-x86_64-apple-darwin.tar.gz
- Apple Silicon (M-series):
- Put
bin/volesomewhere on your PATH (e.g.~/.local/bin) and keep the bundledshare/vole/rulesfolder
Example (Apple Silicon / v2.19.1; use the exact filenames from the Release page):
curl -LO https://github.com/wukongnotnull/vole/releases/download/v2.19.1/vole-2.19.1-aarch64-apple-darwin.tar.gz
tar xzf vole-2.19.1-aarch64-apple-darwin.tar.gz
mkdir -p ~/.local/bin ~/.local/share/vole
install -m 755 vole-2.19.1-aarch64-apple-darwin/bin/vole ~/.local/bin/vole
cp -R vole-2.19.1-aarch64-apple-darwin/share/vole/rules ~/.local/share/vole/If Terminal says vole: command not found, add this to ~/.zshrc, then run source ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"# Day to day
vole # interactive home (easiest)
vole status # machine health
vole analyze # what's using disk
vole clean # scan → confirm → clean (Trash by default)
vole uninstall # interactive app uninstall
vole optimize # system maintenance
vole history # review past work
# Preview only—nothing deleted yet
vole clean --plan
vole uninstall --plan
vole optimize --plan
vole purge --plan
vole installer --plan
vole worktree --plan
# Apply after you review
vole clean --apply <plan.json>
vole uninstall --apply <plan.json>
# Other common
vole touchid status # sudo Touch ID status
vole update # upgrade to a newer release
vole remove --plan # uninstall Vole itself (preview)
vole --help
vole --versionTrash by default. Permanent delete only when you explicitly choose it.
Run bare vole in Terminal to open the interactive home menu.
| Command | Alias | What it does |
|---|---|---|
vole |
— | Interactive home (Clean / Uninstall / Optimize / Analyze / Status / Worktree) |
vole clean |
— | Clean caches and leftovers |
vole uninstall |
— | Uninstall apps and leftovers |
vole optimize |
optimise |
System optimization / maintenance |
vole status |
— | Live health panel (CPU / memory / disk) |
vole analyze |
analyse |
Directory size analysis (starts in your home folder) |
vole history |
— | Operation history and deletion log |
vole purge |
— | Clear stale project build artifacts |
vole worktree |
— | List leftover Git worktrees and move them to Trash after confirm |
vole installer |
— | Find and clean installers |
vole touchid |
— | Configure sudo Touch ID (status / enable / disable) |
vole update |
— | Self-update (network only when you run it) |
vole remove |
— | Uninstall Vole itself |
vole completions |
completion |
Generate shell completions |
vole help |
— | Help (also -h / --help) |
vole --version |
-V |
Print version |
You ❯ vole clean → review candidates → confirm
Vole ❯ ✓ Lists candidates first—nothing is deleted yet
✓ Trash by default (recoverable)
✓ Re-checks protected paths before applying
✓ Skips when unsure—never expands delete scope quietly
| Principle | Meaning |
|---|---|
| Preview before act | Terminal asks for confirmation; or use --plan to look only |
| Recoverable by default | Personal files go to Trash |
| Clear reporting | Distinguishes Trash vs permanent delete |
| Auditable | Review with vole history |
Everyday cleanup stays on your Mac. Network is used only when you run vole update.
Q: Does it delete without asking?
A: Running clean / optimize in Terminal asks for confirmation (default No). Use --plan first if you want a list only.
Q: I deleted the wrong thing?
A: Default is Trash—restore from Trash. Permanent delete cannot be restored that way.
Q: App already gone vs still installed?
A: Leftovers after uninstall → vole clean. App still installed → vole uninstall.
Q: vole: command not found?
A: Make sure the install path is on your PATH (see ~/.local/bin above), then open a new Terminal window.
Q: Prefer a GUI?
A: Use Vole for macOS—same cleanup power in a native window app (Apple Silicon and Intel).
Q: What’s the relationship to Mole?
A: Rules and safety ideas were inspired by Mole. Vole is an independent open-source project and is not affiliated with Mole.
Vole for macOS is the companion app: sidebar Clean, Uninstall, Optimize, Purge, Installer, Analyze, History, Status; Full Disk Access; optional Root privileged helper for some system paths.
Latest desktop build: vole-macos Releases (currently v0.2.0 Universal DMG).
Same cleanup power · same safety habits · Terminal or window—your choice
悟空非空也 (Wukong) — Founder of Way to AI, indie developer, content creator.
| Platform | Link |
|---|---|
| 🌐 Website | waytoai.cn |
| 𝕏 Twitter | 悟空非空也 |
| 📺 Bilibili | 悟空非空也 |
| 悟空非空也 | |
| 📕 Xiaohongshu | 悟空非空也 |
| Search「悟空非空也」 |
Thanks to these products and open-source projects for pioneering macOS cleanup UX—Vole learned a lot from them:
- Mole — open-source cleaner; major inspiration for rules and safety
- CleanMyMac — reference for polished desktop cleanup UX
- Tencent Lemon — familiar system-cleaner experience for Chinese users
Vole is an independent open-source project and has no affiliation or commercial relationship with the above.
Vole is licensed under GPL-3.0.
Rules and safety ideas were inspired by Mole. Vole is an independent open-source project and is not affiliated with Mole.
If you fork it into your own product, please rename it to avoid confusion and credit Mole / Vole as sources.
GPL-3.0 license © 悟空非空也