| name | dev-clean-mac |
| description | Reclaim disk space on a Mac dev machine by deleting regenerable dev caches (Cargo/zfb build output, node_modules, pnpm/npm caches, OS/app caches) and thinning APFS local snapshots so the space actually frees. Manual-only — invoke with /dev-clean-mac when a Mac is low on disk. |
| disable-model-invocation | true |
| argument-hint | [--keep-node-modules] |
Dev Clean Mac
Frees disk on a Mac dev machine by deleting caches and build artifacts that
regenerate on demand. Tuned for this layout — $HOME/repos (with myoss/zfb),
a shared Cargo target dir, pnpm/npm caches — but every step is existence-guarded,
so it runs safely on any Mac with a similar structure (e.g. a second machine).
Why a script and not ad-hoc rm: on APFS, deleting files frees nothing while
local Time Machine snapshots still reference the data — df keeps showing the old
number. The script ends by thinning those snapshots (tmutil thinlocalsnapshots),
which is what makes the reclaimed space materialize. Skipping that step is the #1
reason a cleanup "does nothing."
Workflow
The script lives at scripts/clean-mac.sh in this skill directory.
-
Dry run first — show the user what will be freed, delete nothing:
bash "$HOME/.claude/skills/dev-clean-mac/scripts/clean-mac.sh" --dry-run
Relay the per-path sizes and the measured total to the user.
-
Confirm node_modules. By default the script deletes all node_modules
under $HOME/repos (reinstallable via pnpm/npm install). If the user is
mid-work on a project, pass --keep-node-modules to preserve them.
-
Run for real:
bash "$HOME/.claude/skills/dev-clean-mac/scripts/clean-mac.sh" --run
bash "$HOME/.claude/skills/dev-clean-mac/scripts/clean-mac.sh" --run --keep-node-modules
The deletions can take a few minutes (millions of small files); it may
auto-background. Report the BEFORE/AFTER df lines it prints.
What it cleans
-
Cargo: the shared target-dir from $HOME/.cargo/config.toml (defaults to
$HOME/.cargo-target, dominated by zfb), $HOME/.cargo/registry, and every
per-project target/ under $HOME/repos (detected by cargo's CACHEDIR.TAG).
-
zfb: checked-in release tarballs (zfb-*.tar.gz) and all .zfb-build/ dirs.
-
node_modules: every one under $HOME/repos (unless --keep-node-modules).
-
JS caches: pnpm store prune, npm cache clean, $HOME/Library/Caches/pnpm.
-
OS/app caches: ms-playwright, electron, copilot, $HOME/.cache/codex-runtimes,
Homebrew cache, Adobe/CreativeCloud logs, unavailable iOS simulators.
-
Downloads: *.dmg / *.pkg installers (re-downloadable).
-
APFS local snapshots: thinned at the end to release everything above.
What it never touches
Source trees, image/data stashes (e.g. zmod-image-stash), browser profiles,
and app data (Claude/Chrome/Slack containers) — only regenerable caches and
artifacts. Every path is verified to be under $HOME before removal; missing
paths are skipped silently, which is what makes it portable across machines.
Notes
-
First builds/installs after running are slower (caches re-download, projects
rebuild) — that's the expected trade for the space.
-
Safe to re-run anytime; all steps are idempotent.
-
Local Time Machine snapshots are convenience restore points, not your real
backup — thinning them does not affect Time Machine backups on disk/network.