Mole Mac Cleanup

Mole Mac Cleanup

Use the official Mole agent skill at tw93/Mole/.claude/skills/mole/SKILL.md as the command-semantics baseline. The repo-only runtime.yaml pins the audited upstream version. For version-sensitive behavior, confirm the installed version and read mo <command> --help; trust the actual dry-run over stale assumptions.

Safety Contract

1. Always preview before deletion. Run the matching --dry-run, inspect its candidates, summarize the impact, and obtain explicit user confirmation in the current turn before running the destructive command.
2. Treat clean, uninstall, purge, installer, and optimize as destructive. Treat update, remove, and whitelist changes as state-changing and require an explicit request.
3. Never parse or act from a TUI frame. Use JSON surfaces where available. If a selector opens, do not infer a selection or press bulk-select keys on the user's behalf.
4. Never invent flags. Run mo <command> --help when the documented surface is insufficient.
5. Preserve Mole's safety layer. Use mo clean --whitelist for protected paths; never replace Mole with raw rm, hand-written recursive deletion, or broad globs.
6. Do not request sudo, close applications, remove login items or dotfiles, prune Docker/OrbStack, or delete virtualenvs and project artifacts unless the user separately confirms that exact scope.
7. Bound long scans and watches. Send progress updates, stop low-value scans that remain silent, and never leave mo status --watch running in the background.

Establish the Runtime

Confirm the binary, version, and real package manager:

command -v mo
mo --version
brew list --versions mole
brew info mole --json=v2

Do not trust the Install: line from mo --version alone; a Homebrew-managed build can report Manual. If brew list --versions mole succeeds, manage it with Homebrew.

Choose the Surface

Interactive analyze, terminal-attached status, app selectors, and installer selectors are human surfaces. Prefer the commands above. If a dry-run still opens a selector, stop after reporting the visible candidates and ask the user to make the selection.

Machine-Readable Evidence

Disk analysis

mo analyze --json returns one JSON object containing path, overview, and entries[]. Each entry includes name, path, size, is_dir, and insight; sizes are bytes. Scope expensive scans when possible, for example:

mo analyze --json "$HOME/Library"

Cleanup candidates

mo clean --dry-run prints a summary and writes the candidate paths to:

~/.config/mole/clean-list.txt

Read that file when exact paths matter. purge --dry-run and installer --dry-run report their candidates in the terminal and do not write this list.

Cleanup history

mo history --json --limit N returns session summaries and the operation/deletion log paths. Use actions.removed, trashed, skipped, and failed to verify the outcome. When failed is nonzero, inspect only the matching session in the operations log and classify permission-protected or running-app paths separately from real cleanup failures.

Installed apps

mo uninstall --list prints the app inventory as a JSON array when stdout is not a TTY. Each entry has name, bundle_id, source, uninstall_name, path, and size. Read uninstall_name for the exact argument mo uninstall accepts, so the app selector TUI never has to be opened.

mo uninstall --list

System status

Use mo status --json for a single CPU, memory, disk, and network snapshot. mo status --watch --interval 1s emits NDJSON; collect only the number of samples needed, then terminate it.

Command Notes

• mo clean permanently removes caches and also sweeps evidence-backed leftovers from already-uninstalled apps. It does not uninstall an installed app.
• mo uninstall moves the app and matched leftovers to Trash by default, so they remain recoverable until Trash is emptied.
• mo clean --external <path> cleans macOS metadata from an external volume; resolve and show the exact mounted path before asking for confirmation.
• In current upstream Mole, mo purge targets both local build output (target/, build/, dist/, .next/) and dependency directories that require a network to restore (node_modules/, Pods/, venv/, vendor/). A purge is therefore not always recoverable offline: classify the dry-run candidates by recovery type and show that distinction before requesting confirmation. Add --include-empty to surface zero-size candidates. mo purge --paths opens an interactive editor for the scan directories; it is a human surface, so report that the user has to edit it themselves instead of entering it.
• mo optimize refreshes caches and system services rather than only deleting files. Explain the planned effects before requesting approval.
• Use --debug only to diagnose a command that did nothing or failed; normal runs should stay concise.

Upgrade Mole

If Homebrew manages Mole, prefer:

brew upgrade mole

Otherwise, upstream provides mo update. mo update --nightly installs unreleased main; never run it unless the user explicitly requests nightly. After any upgrade, verify the installed version and run a non-destructive smoke test:

mo --version
mo clean --dry-run

Report and Verify

Before cleanup, report the command, potential bytes/items, largest categories, exact risky paths, protected/running-app skips, and the proposed real command. After an approved cleanup:

1. Compare free space before and after.
2. Read mo history --json --limit 1.
3. Explain nonzero failed and important skipped counts without escalating to sudo automatically.
4. Verify separately protected paths still exist when the dry-run surfaced dotfiles, login items, Docker data, dependency stores, virtualenvs, or active project state.

The dry-run is the practical undo for mo clean, because clean deletions are normally permanent. If a user asks whether Mole removed a specific file, use the deletion log path returned by history and answer from the exact matching record.