Drive Mole (`mo`), tw93's GPL-3.0 macOS maintenance CLI that cleans caches and app leftovers, uninstalls apps with their remnants, purges rebuildable project artifacts, removes downloaded installers, explores disk usage, runs bounded system optimization, and reports live health. Routes one request to one mode: run a command safely (`--dry-run` first, the user runs the destructive step), consume the JSON/NDJSON agent surfaces (`mo analyze --json`, `mo status --json` / `--watch`, `mo history --json`, `~/.config/mole/clean-list.txt`), install/update/remove on the right channel, configure whitelists and scan paths, troubleshoot, or contribute to the repo. Use when a user wants to free Mac disk space or fully uninstall a Mac app. Triggers on: mole, `mo clean`, `mo uninstall`, `mo analyze`, `mo purge`, `mo status`, tw93/Mole, mole.fit, clean my Mac, what is eating my disk, CleanMyMac / AppCleaner / DaisyDisk alternative, brew install mole.
Drive Mole (`mo`), tw93's GPL-3.0 macOS maintenance CLI that cleans caches and app leftovers, uninstalls apps with their remnants, purges rebuildable project artifacts, removes downloaded installers, explores disk usage, runs bounded system optimization, and reports live health. Routes one request to one mode: run a command safely (`--dry-run` first, the user runs the destructive step), consume the JSON/NDJSON agent surfaces (`mo analyze --json`, `mo status --json` / `--watch`, `mo history --json`, `~/.config/mole/clean-list.txt`), install/update/remove on the right channel, configure whitelists and scan paths, troubleshoot, or contribute to the repo. Use when a user wants to free Mac disk space or fully uninstall a Mac app. Triggers on: mole, `mo clean`, `mo uninstall`, `mo analyze`, `mo purge`, `mo status`, tw93/Mole, mole.fit, clean my Mac, what is eating my disk, CleanMyMac / AppCleaner / DaisyDisk alternative, brew install mole.
allowed-tools
Bash Read Write Edit Glob Grep
compatibility
macOS only (10.14+, Intel and Apple Silicon); `install.sh` hard-fails on non-Darwin. Windows support is an experimental `windows` branch. Needs the stock Bash 3.2+ and admin rights for some cleanup. Full Disk Access is recommended, not required. Optional `fd` speeds up `purge`/`installer`. Go 1.24+ only to build the `analyze`/`status` TUI binaries. The CLI is GPL-3.0; the "Mole for Mac" GUI at mole.fit is a separate paid product.
Mole is a terminal-first macOS maintenance toolkit: a Bash CLI (mole, aliased
mo) plus two Go/Bubble Tea TUI binaries (analyze-go, status-go). It
reclaims disk space, removes apps together with their remnants, purges
rebuildable project artifacts, and reports system health — with dry-run
previews, path protection, and an operations log on every destructive path.
It deletes files on someone's live machine. That single fact drives every
rule below.
When to use this skill
A user wants to free disk space, find what is eating their disk, or fully
uninstall a Mac app including leftovers
Reading Mole's machine-readable output (--json / --watch / the dry-run
list file) instead of scraping a TUI
Installing, updating, or removing Mole, or untangling a Homebrew-vs-script
install-channel conflict
Configuring whitelists, purge scan paths, shell completion, or Touch ID
Diagnosing a Mole run that skipped everything, hung, or asked for permissions
Contributing to the tw93/Mole repo (Bash 3.2 + Go, bats tests, the
# SAFE: deletion contract)
When not to use this skill
Non-macOS cleanup, or Linux/Windows disk tooling → Mole is Darwin-only
Questions about the paid Mole for Mac GUI (mole.fit) → separate
closed-source product, not this repo; the CLI is not a feature mirror of it
Generic "delete these files for me" work with no Mole involved → use plain
shell; do not route arbitrary deletions through Mole
Package management, app installation, or background monitoring → explicitly
out of scope per the project's own product filter
Instructions
Step 0: The five rules (non-negotiable)
These come from the project's own agent guide
(.claude/skills/mole/SKILL.md upstream) and override convenience:
Preview before you delete. Always. Every destructive command takes
--dry-run. Run it, show the user what would go, then offer the real run.
The dry-run is the undo.
The user runs the destructive command, not you — unless they asked for
it in this turn. "Clean my Mac" is such an ask; "why is my disk full" is not.
Never parse a TUI frame.mo analyze and TTY-attached mo status are
full-screen Bubble Tea programs whose output is drawn, not printed. Use the
JSON surfaces.
Never invent flags. The surface is small. If it is not in
references/commands.md, run mo <command> --help. There is no --yes
and no --force on the cleanup commands.
Protection is a whitelist, not an argument. To keep a cache, use
mo clean --whitelist — never a hand-rolled find/rm around the safety
layer.
Step 1: Pick exactly one mode
Mode
Use when
Go to
run-command
the user wants space freed, an app gone, projects purged
Step 2: run-command — map the question to one command, preview, hand over
The user asks
Command
"What is eating my disk?"
mo analyze --json (or scope it: mo analyze ~/Library --json)
"Free up space"
mo clean --dry-run → review → mo clean
"Remove this app completely"
mo uninstall --dry-run <app> → mo uninstall <app>
"My Mac feels slow" / caches look broken
mo optimize --dry-run → mo optimize
"Clean up my old projects"
mo purge --dry-run → mo purge
"Get rid of downloaded installers"
mo installer --dry-run → mo installer
"What did Mole delete?"
mo history --json --limit 20
Two things to say out loud before a real run:
mo clean and mo purge delete permanently.mo uninstall and
mo analyze route through Trash. Say which one applies.
mo optimize is the destructive command whose effect is not "files
disappear" — it flushes DNS, rebuilds Finder/icon caches, and touches
system services. Describe what it will do first.
For mo purge, distinguish locally rebuildable output (target/, build/,
dist/, .next/) from network-restorable dependencies (node_modules/,
Pods/, venv/, vendor/). The second kind is not recoverable offline.
Step 3: automate — use the four machine-readable surfaces
mo analyze --json ~/Library # one JSON object: entries[], large_files[], totals
mo status --json # one health snapshot
mo status --watch --interval 1s # NDJSON stream — BOUND IT, then terminate
mo history --json --limit 20 # sessions[] + the log pathscat ~/.config/mole/clean-list.txt # every candidate from the last `mo clean --dry-run`
~/.config/mole/clean-list.txt is written by mo clean --dry-run only.
mo purge --dry-run and mo installer --dry-run print candidates to the
terminal and write no file.
mo status auto-switches to JSON when stdout is not a TTY, but pass --json
explicitly in scripts so intent stays obvious. Never leave --watch running
unbounded in the background.
Schemas and flags: references/commands.md.
Read-only helper: bash .agent-skills/mole/scripts/mole.sh doctor.
Step 4: install-update — pick the channel and stay on it
install.shrefuses when it detects a Homebrew-owned install. Use
brew upgrade mole, or brew uninstall --force mole first.
mo update --nightly is script-install only. Homebrew users upgrade
with brew upgrade mole.
The positional token latest is a legacy alias for main — it installs
unreleased code, not the newest stable release. Pass a real tag
(1.51.0 / V1.51.0) if you want a pinned release.
Installing to the default /usr/local/bin prompts for an admin password on
every update. --prefix "$HOME/.local/bin" keeps future mo update
password-free.
install.sh is fail-closed: a checksum or attestation mismatch aborts and says
why; it never silently downgrades to a source build. Do not work around that.
Uninstall Mole itself with mo remove (--dry-run supported).
Step 5: configure — everything is a file under ~/.config/mole/
mo clean --whitelist # protected caches -> ~/.config/mole/whitelist
mo optimize --whitelist # protected maintenance -> ~/.config/mole/whitelist_optimize
mo purge --paths # scan dirs -> ~/.config/mole/purge_paths
mo completion # auto-detect shell and install
mo touchid enable|disable|status
Default purge scan dirs when purge_paths is unset: ~/Projects, ~/GitHub,
~/dev. Once custom paths are configured, only those are scanned.
Environment knobs (full list in references/commands.md): MO_DEBUG=1,
MO_NO_OPLOG=1, MOLE_OPLOG_PATH, MO_USE_FIND, MO_LAUNCHER_APP,
MOLE_ENABLE_DISK_VERIFY=1.
Step 6: troubleshoot — check the four usual causes first
Permissions. Most "it skipped everything" reports are TCC. Grant Full
Disk Access to the terminal app in System Settings; Trash failures may also
need App Management or App Data.
"Bundled analyzer binary not found."bin/analyze-go / status-go are
missing — reinstall or mo update.
Channel conflict. See Step 4; install.sh refusing a Homebrew install
is intentional.
"Did Mole take my file?" Do not guess. mo history --json names the
deletions log; every deletion is one tab-separated line (timestamp, mode,
size, status, path). Read the actual line, then add the path to
mo clean --whitelist so the next run leaves it alone.
Add --debug to any command when it silently did nothing. Do not leave it on.
Known limits and the full protection model: references/safety.md.
Step 7: contribute — the safety contract is the review gate
git clone https://github.com/tw93/Mole.git && cd Mole
brew install shfmt shellcheck bats-core golangci-lint
git config core.hooksPath .githooks
make build # -> bin/analyze-go, bin/status-go
./scripts/check.sh --format
MOLE_TEST_NO_AUTH=1 ./scripts/test.sh
go test ./...
Read AGENTS.md in the repo first — CLAUDE.md is a symlink to it and it is
the cross-agent source of truth. Hard rules: route deletions through
mole_delete / safe_remove in lib/core/file_ops.sh; raw rm -rf needs an
inline # SAFE: <reason> annotation that CI checks for; Bash 3.2 compatible
with BSD (not GNU) command flags; never let verification block on a real sudo
or osascript prompt — use MOLE_TEST_NO_AUTH=1.
Details and hotspot ownership: references/contributing.md.
Best practices
Dry-run, then hand the keyboard back. The preview is the only step the
user can veto, and for mo clean / mo purge it is the only undo.
Read ~/.config/mole/clean-list.txt, not the terminal summary, when you
need to reason about or show exactly what a real mo clean would remove.
Say which deletion mode applies before every real run: permanent
(clean, purge, installer) vs Trash (uninstall, analyze).
Never scrape the TUI.--json / --watch exist precisely so you do not
have to; a drawn frame is not a stable interface.
Bound --watch. Collect the samples the question needs, then terminate.
Never leave a monitor running in the background.
Stay on one install channel. Homebrew and script installs do not mix,
and --nightly only exists on the script channel.
Whitelist instead of narrowing the command. Mole's protection lists are
the supported way to spare something; hand-rolled deletion around them
loses path validation, Trash routing, and the operations log.
Do not run mo update on a user's behalf unless they asked — and never
--nightly, which installs unreleased main.
Trust the refusals. "When Mole cannot prove an item is safe to change,
it skips or refuses it." A skip with a reason is the product working, not a
bug to route around.
Report the largest entries[] and any insight: true rows. Do not chain
into mo clean — the user asked a question, not for a cleanup.
Example 2: "Clean my Mac" — preview, show, then hand over
mo clean --dry-run
cat ~/.config/mole/clean-list.txt
Summarize the candidate list by category and total size, warn that mo clean
deletes permanently, then let the user run mo clean themselves.
Example 3: Fully uninstall an app
mo uninstall --list # exact name Mole accepts
mo uninstall --dry-run slack # review app + leftovers
mo uninstall slack # routes through Trash
Example 4: Short diagnostic time series
mo status --json # one snapshottimeout 10 mo status --watch --interval 1s # ~10 NDJSON lines, then stop
Example 5: Check the environment before recommending anything
bash .agent-skills/mole/scripts/mole.sh doctor
bash .agent-skills/mole/scripts/mole.sh surfaces
doctor reports macOS/arch, whether mo is installed and by which channel,
version, config/log presence, and optional fd — without installing,
updating, or deleting anything.
