vole

Screenshots

Run vole in Terminal to open the interactive home menu—arrow keys to move, Enter to select.

The home menu lists seven items: Mole-aligned Clean / Uninstall / Optimize / Analyze / Status, plus Vole-native Worktree (6) and Agent (7, Remove leftover agent data, digit 7). Items 1–6 are unchanged. Worktree and Agent are extras, not Mole command-surface gaps.

Features

Type vole in Terminal for an interactive home menu. About 550 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.

Install

Requires macOS 12+.

Current release: v2.20.0 (Developer ID signed and notarized). Builds for Apple Silicon and Intel.

Product “v3” is a CLI generation name. Package versions stay on 2.x MINOR (now 2.20.0), not 3.0.0. Homebrew users stay on this repo’s tap; we do not publish vole to Homebrew core. The next MINOR is triggered by user-visible work already on main; whether to tag a release is asked separately.

Option 1: Install with an AI prompt

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 / purge / worktree / agent or any command that changes the system. Do not submit or install a Homebrew core formula.

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

Option 2: Homebrew

brew tap wukongnotnull/vole https://github.com/wukongnotnull/vole
brew install vole

Then run vole. If brew fails or the version looks wrong, use the download option below.

Option 3: Download

1. Open the latest Release
2. Download the archive for your chip:
   • Apple Silicon (M-series): …-aarch64-apple-darwin.tar.gz
   • Intel: …-x86_64-apple-darwin.tar.gz
3. Put bin/vole somewhere on your PATH (e.g. ~/.local/bin) and keep the bundled share/vole/rules folder

Example (Apple Silicon / v2.20.0; use the exact filenames from the Release page):

curl -LO https://github.com/wukongnotnull/vole/releases/download/v2.20.0/vole-2.20.0-aarch64-apple-darwin.tar.gz
tar xzf vole-2.20.0-aarch64-apple-darwin.tar.gz
mkdir -p ~/.local/bin ~/.local/share/vole
install -m 755 vole-2.20.0-aarch64-apple-darwin/bin/vole ~/.local/bin/vole
cp -R vole-2.20.0-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"

Usage

Common commands

# 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
vole agent --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 --version

Trash by default. Permanent delete only when you explicitly choose it.

All commands

Run bare vole in Terminal to open the interactive home menu.

Safety

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

Everyday cleanup stays on your Mac. Network is used only when you run vole update.

FAQ

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.

Prefer a desktop app?

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

About

悟空非空也 (Wukong) — Founder of Way to AI, indie developer, content creator.

Credits

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.

License

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 © 悟空非空也

内容由编辑整理，部分信息来自 GitHub 与项目官网，版权归原作者所有。发现错误？报告问题