SkillAgentSearch skills...

macos-cleaner

Diagnoses and safely reclaims macOS disk space: caches, logs, app remnants, large/duplicate files, Docker/OrbStack, Chromium code-sign clones, developer caches

Install / Use

npx skills add daymade/claude-code-skills --skill macos-cleaner

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

93/100

Category

Operations

Supported Platforms

Universal

Our assessment of macos-cleaner

macos-cleaner scores 93/100 on our quality scale, 180th of 746 Operations skills we index (top 25%).

Its SKILL.md is 32 KB long, well organised into 15 sections with 5 code examples: a thorough specification that gives an agent plenty to work with.

With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
13/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so macos-cleaner is actively maintained.
  • Our last check on 2026-10-26 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

macos-cleaner compared with similar skills

All 4 of these similar skills score higher than macos-cleaner; compare them before choosing.

SkillScoreStarsUpdatedFormat
macos-cleaner (this skill)by daymade931.4k53d agoSKILL.md
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md
designby nextlevelbuilder100149.0k6d agoSKILL.md

Frequently asked questions

How do I install macos-cleaner?
Run npx skills add daymade/claude-code-skills --skill macos-cleaner. The install tabs above show the steps for each supported agent.
Which AI agents does macos-cleaner work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is macos-cleaner safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is macos-cleaner still maintained?
The repository was last updated about 2 months ago, so macos-cleaner is actively maintained.

name: macos-cleaner description: >- Diagnoses and safely reclaims macOS disk space: caches, logs, app remnants, large/duplicate files, Docker/OrbStack, Chromium code-sign clones, developer caches. Use when a Mac is low on storage, shows “Caching needs more space”, or before deleting anything to avoid data loss. Not for Windows/Linux or permission issues (use macos-permissions).

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 user asks what has been growing or filling the disk lately, free space fell between two readings, or an older scan export exists (GrandPerspective text export, saved du output) | Read references/growth_attribution.md; answer with a delta table whose rows name their writer, not a size ranking | | 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 — and check them for known defects first. Prefer an application's supported cache-management command or an exact object ID. "Official" and "precise" are not evidence of safety, so before the first supported-control command runs, do a known-issue check on that exact command at the installed version: a search of the tool's issue tracker for the command name, plus its changelog for fixes landing in a later release than the one installed. A command with an open, version-relevant defect is not a supported control for this skill — treat it like the category-wide commands in the next rule and either upgrade past the fix or use an exact-path alternative. 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.

  11. Before promising physical release from any deletion, name the mechanism — and get it from the creating command, not from a guess. A df gap between a nominal du total and actual reclaim means one candidate mechanism is at work, and the strongest evidence is the verbatim command that created the folder, because the copy verb alone decides the space semantics. Find it in session history before theorizing; a folder-name or size-based inference is not a mechanism. Only if no command can be found does the gap stay unknown — do not substitute the most plausible-sounding mechanism for one you can demonstrate.

    The mechanisms, distinguished by what du reports and what deletion releases (all four measured on 2026-09-19, 1 GiB source, drift-controlled):

    | Created by | du nominal | Deleting the copy releases | Fingerprint | |---|---|---|---| | cp (bare) / cp -a | full, counted per path | full | independent inodes, independent extents | | cp -c / cp -cR (clonefile) | full, counted per path | ≈0 | different inode, nlink=1, shared extent | | ln / cp -l (hard link) | counted once — sibling reads 0 | ≈0 | same inode, nlink=2 | | local APFS snapshot | full | ≈0 until snapshots are thinned | tmutil listlocalsnapshots / |

    Two traps this table exists to kill. The clonefile and hard-link rows are opposite on du but identical on deletion — both release ≈0, so "deleting it freed nothing" cannot tell them apart, while du can: a hard-linked sibling counts once (or as 0), a clonefile copy counts full. And calibrating the wrong copy verb proves nothing: a 98 GiB gap was twice attributed to the wrong mechanism because the probe used bare cp when the folder had been built with cp -cR. Before any deletion, run the probe with the same flags as the creating command. Clonefile is worth flagging as the common case — macOS cp defaults to it for -c, and directories copied for a delivery/kit routinely carry it.

Phase contract

Use this state machine for every cleanup:

  1. Observe — read-only. Capture identity, disk baseline, the suspected subsystem's status and configuration, physical allocation, and critical-service health. 1b. Authorize stateful inspection when unavoidable. If deeper evidence requires creating a temporary container, pulling an image, mounting a volume, or writing a snapshot, first finish the metadata-only observation, list the exact inspection commands and their side effects, and obtain separate approval. Inspection approval is not cleanup approval.
  2. Plan — no mutation. Pass the Phase 2 entry gate first (four steps: target confirmation, classification table, gate rules, checker — see below), then explain findings, commands, impact, recovery, expected release, and success criteria. Stop at the confirmation gate.
  3. Execute — approved scope only. Re-read live state immediately before acting, then run each approved command separately and check its exit status and postcondition.
  4. Verify — independent readback. Measure disk space and subsystem state again, recheck protected services, and observe long enough to detect immediate refill.

Do not compress phases 2 and 3 into one message. A plan printed beside a cleanup command is not a confirmation gate.

Phase 1: read-only diagnosis

Establish the baseline

At minimum, capture:

/bin/date "+%F %T %Z %z"
/usr/sbin/scutil --get ComputerName
/usr/sbin/scutil --get LocalHostName
/usr/bin/sw_vers
/bin/df -k /System/Volumes/Data
/bin/df -h /System/Volumes/Data

Use df -k for calculations and df -h for the human-readable report. Treat an extension, label, or old report as a hint until the live command confirms it.

Establish the success target before an unknown-source scan. Copy a user-supplied free-space or capacity target exactly. If the user supplied none, report the current values and ask for a target in GiB, capacity percentage, or both; do not invent one. A named-suspect diagnosis may continue without a cleanup target, but the ordered unknown-source scan cannot claim a stop condition until the target is explicit.

Keep this first phase read-only. Do not run scripts/cleanup_report.py yet: it creates a local state directory and snapshot file. Preserve the command output in the report instead. On a remote target, always run the direct df commands on that host; the local helper must not measure the controller Mac by mistake.

Follow the named suspect before broad scans

  • Query the subsystem's own status and settings.
  • Measure physical allocation with a bounded du on the exact data path only when permissions and user scope allow it.
  • Distinguish logical content size, sparse-file apparent size, purgeable space, and physically allocated bytes.
  • For APFS clones, label du as path-accounted or nominal rather than physical: shared extents can be attributed to every path, so actual release remains unknown until deletion and df readback.
  • For a suspected growing log, record exact file sizes at two or more timestamps. One large file or one recent mtime does not prove sustained growth.
  • Capture the current process, listeners, launch mechanism, and supported health probe of any co-resident service the user marks as critical. Re-resolve PIDs at each checkpoint.

If the known suspect alone can meet the user's free-space target, do not scan unrelated personal or development directories “just in case.”

General analysis when the source is unknown

Run the smallest ordered sequence that can identify enough physical space to meet the target. Stop only when candidates with supported exact actions and defensible expected physical release can meet it. Raw allocation totals, logical cache sizes, shared Docker layers, Trash moves, and unverified “potential savings” do not satisfy the stop condition.

Do not make the physical-confidence ranking hide the user's largest visible hotspot. When a nominal/path-accounted candidate is larger than the recommended action, show both numbers and explain why its physical release is uncertain. Rank by defensible physical release, safety, and effort; report nominal size as a separate column instead of

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars1.4k
CategoryOperations
Updated1mo ago
Forks219

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions