macos-cleaner

macOS Cleaner

Diagnose the actual source of disk pressure, reclaim only approved space, and prove that the cleanup did not damage user data or co-resident services.

Entry router

Choose the narrowest path that can answer the request:

User signal	Route
Apple Content Caching, AssetCacheManagerUtil, CacheUsed, ActualCacheUsed, iCloud cache, or “Caching needs more space”	Read references/apple_content_caching.md completely before probing or proposing commands
Docker, OrbStack, images, containers, or volumes	Read references/docker_analysis.md; inspect every object and never use prune-family commands
Docker build cache	Measure with docker builder du; this skill reports it but does not delete it because Docker exposes category-wide prune controls rather than per-record intent
Chrome, ChromeDriver, Playwright, Codex Computer Use, Edge, or Chromium has large *.code_sign_clone directories	Read references/chromium_code_sign_clones.md completely; use the bundled analyzer to separate active, inactive, and unknown exact children and never equate du with physical release
A named cache, directory, application, or service is already the suspect	Inspect that target first and read the matching semantics in references/cleanup_targets.md; do not start a home-directory or whole-disk scan
The source is genuinely unknown	Use the general analysis workflow below; Mole is optional, not the universal first step

User-provided scope exclusions override every generic scan suggestion. Do not inspect personal directories, credentials, databases, application state, or unrelated services when the user excludes them.

Safety and authorization contract

1. Separate observation from mutation. Complete a read-only diagnosis first. Do not delete, stop a service, edit settings, install or upgrade tools, or run a cleanup preview that may mutate state during that phase.
2. Confirm the exact target. On a remote Mac, record the current host identity before any other work. Never infer the machine from an IP, old PID, directory name, or prior report.
3. Plan before asking. Before any state change, list every command, what it changes, expected physical space reclaimed, impact, recoverability, and postconditions. Then stop if the user requested a plan-only phase.
4. Require explicit approval. If the user supplies an exact confirmation phrase, require that phrase. Otherwise ask for unmistakable approval of the listed commands and targets. Approval for one plan does not authorize a fallback or a wider cleanup.
5. Use precise supported controls. Prefer an application's supported cache-management command or an exact object ID. If no supported control exists, an exact application-owned cache directory may be removed only after verifying its owner, confirming the application is stopped or the directory is otherwise inactive, explaining rebuild/redownload impact, and receiving approval. Never target a broad cache root or active application state.
6. Never use Docker prune-family commands. This includes image, container, volume, system, builder, and buildx prune. Category-wide deletion cannot express per-object user intent.
7. Avoid broad destructive shell forms. Do not recommend or execute broad rm -rf or glob deletion. For exact approved ordinary files, prefer Finder Trash. The bundled legacy helper permanently deletes and has only the limited guards documented below; never treat it as equivalent to Trash.
8. Preserve valuable state. Never target user documents, credentials, SSH material, active databases, application configuration, or running-service state merely to increase the reported savings. Read references/safety_rules.md before any file deletion.
9. Execution follows the user's authorization. If the user asks only for analysis or wants to run commands personally, hand off the commands. If the user asks the agent to fix the machine and explicitly confirms the scoped plan, execute the exact approved commands and verify them. Unattended recurring deletion logic needs separate approval before it is written or enabled.
10. Fail fast. An unexpected non-zero command, a mismatched postcondition, an unexpected target, or a changed dependency stops the cleanup. Interpret documented probe statuses such as lsof exit 1 with empty output before deciding they are failures. Report the partial state; do not improvise a fallback.