Vole

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

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

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
Agent	List leftover agent containers, sessions, and caches; confirm, then Trash

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.

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

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
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.

Command	Alias	What it does
`vole`	—	Interactive home (Clean / Uninstall / Optimize / Analyze / Status / Worktree / Agent)
`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 agent`	—	List leftover agent data; confirm, then Trash（not a git checkout cleaner）
`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

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

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.

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.

Platform	Link
🌐 Website	waytoai.cn
𝕏 Twitter	悟空非空也
📺 Bilibili	悟空非空也
▶️ YouTube	悟空非空也
📕 Xiaohongshu	悟空非空也
💬 WeChat	Search「悟空非空也」

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.

Name		Name	Last commit message	Last commit date
.cursor/rules		.cursor/rules
.github/workflows		.github/workflows
Formula		Formula
conformance		conformance
crates		crates
data		data
docs		docs
images		images
scripts		scripts
tests		tests
third_party		third_party
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.ja.md		README.ja.md
README.ko.md		README.ko.md
README.md		README.md
README.zh-CN.md		README.zh-CN.md
README.zh-TW.md		README.zh-TW.md
install.sh		install.sh
rust-toolchain.toml		rust-toolchain.toml

Navigation Menu

Repository files navigation

Vole

Screenshots

Features

Install

Option 1: Install with an AI prompt

Option 2: Homebrew

Option 3: Download

Usage

Common commands

All commands

Safety

FAQ

Prefer a desktop app?

About

Credits

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Vole

Screenshots

Features

Install

Option 1: Install with an AI prompt

Option 2: Homebrew

Option 3: Download

Usage

Common commands

All commands

Safety

FAQ

Prefer a desktop app?

About

Credits

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages