Immutable. This exact content is served forever at /api/v1/blob/eaeaad42d98d5a05.
--- name: mole-mac-cleanup description: Safely operate the installed Mole CLI (`mo`) on macOS using machine-readable status, analysis, history, and dry-run surfaces. Use when Claude Code is asked to inspect Mac disk, CPU, memory, or network usage; find large files; preview or perform cleanup; remove apps, installers, or project artifacts; diagnose Mole results; or check and upgrade Mole. --- # 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: ```bash 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 | User intent | Agent-facing command | |---|---| | Explain disk usage | `mo analyze --json` or `mo analyze --json <path>` | | Preview safe cleanup | `mo clean --dry-run` | | List installed apps with exact uninstall names | `mo uninstall --list` | | Remove one app completely | `mo uninstall --list` to read the exact name, then `mo uninstall --dry-run <app>` | | Preview bounded maintenance | `mo optimize --dry-run` | | Preview old project artifacts | `mo purge --dry-run` | | Preview downloaded installers | `mo installer --dry-run` | | Audit prior cleanup | `mo history --json --limit 20` | | Capture one health snapshot | `mo status --json` | | Capture a short time series | `mo status --watch --interval 1s` | 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: ```bash mo analyze --json "$HOME/Library" ``` ### Cleanup candidates `mo clean --dry-run` prints a summary and writes the candidate paths to: ```text ~/.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. ```bash 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: ```bash 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: ```bash 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.