75 added, 40 removed. Audit A to A.
---
name: mole-mac-cleanup
- description: Safely use Mole (`mo`) to scan, preview, and clean macOS disk usage. Use when Codex is asked to run Mole, clean Mac caches, find large files, remove project artifacts, preview app leftovers, inspect installer files, or summarize Mole cleanup candidates before any destructive cleanup.
+ description: Safely operate the installed Mole CLI (`mo`) on macOS using machine-readable status, analysis, history, and dry-run surfaces. Use when Codex 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
- ## Core Rule
+ 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.
- Always preview before cleanup. Treat `mo clean`, `mo uninstall`, `mo purge`, `mo installer`, and `mo remove` as destructive unless they include `--dry-run`.
+ ## Safety Contract
- Do not run a destructive Mole command without explicit user confirmation in the current turn. Summarize the dry-run output first, including estimated space, categories, skipped protected/running apps, and any manual review items.
+ 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.
- ## Workflow
+ ## Establish the Runtime
- 1. Confirm Mole is available:
+ Confirm the binary, version, and real package manager:
```bash
command -v mo
mo --version
+ brew list --versions mole
+ brew info mole --json=v2
```
- 2. Pick the safest preview command:
+ 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.
- ```bash
- mo clean --dry-run
- mo purge --dry-run --debug
- mo uninstall --dry-run
- mo installer --dry-run
- mo optimize --dry-run
- ```
+ ## Choose the Surface
- 3. For ad hoc disk exploration, prefer:
+ | User intent | Agent-facing command |
+ |---|---|
+ | Explain disk usage | `mo analyze --json` or `mo analyze --json <path>` |
+ | Preview safe cleanup | `mo clean --dry-run` |
+ | Remove one app completely | `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
- mo analyze "$HOME"
- mo analyze /Volumes
+ mo analyze --json "$HOME/Library"
```
- Use `mo analyze` for exploratory cleanup because upstream documents it as safer for ad hoc cleanup: analyze-driven file removal routes through Finder Trash rather than direct deletion.
+ ### Cleanup candidates
- 4. Review generated detail files when present:
+ `mo clean --dry-run` prints a summary and writes the candidate paths to:
- ```bash
- sed -n '1,160p' "$HOME/.config/mole/clean-list.txt"
- mo history
- mo history --json
+ ```text
+ ~/.config/mole/clean-list.txt
```
- 5. Only after user confirmation, run the matching non-dry-run command.
+ 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.
- ## Reporting
+ ### Cleanup history
- When reporting dry-run results, include:
+ `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.
- - command run and whether it was dry-run
- - total potential space and item count
- - largest categories or paths
- - skipped items and why
- - manual-review candidates, especially login items, dotfiles, Docker/OrbStack data, and active browser/app state
- - exact next command if the user confirms cleanup
+ ### System status
- ## Safety Defaults
+ 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.
- - Do not request sudo unless the user explicitly wants full system-level preview or cleanup.
- - Do not close apps automatically; report when Mole skips running apps such as Chrome or Codex.
- - Do not remove dotfiles, login items, app support data, Docker/OrbStack data, virtualenvs, or project artifacts without a fresh confirmation.
- - Prefer Homebrew management for installation and updates:
+ ## 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 locally rebuildable artifacts such as `target/`, `build/`, `dist/`, and `.next/`, while avoiding dependencies that require a network restore. On older Mole versions, rely on the actual dry-run list and treat any `node_modules`, `Pods`, `venv`, or `.venv` candidate as manual review.
+ - `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 install mole
brew upgrade mole
- brew uninstall 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.