| name | mac-disk-cleanup |
| description | Safely audit and clean macOS disk space with read-only baselines, approval-gated cleanup batches, Docker/Xcode/cache/log cleanup, verification, and task artifacts. Use when the user asks to free Mac disk space, clean Mac storage, reclaim disk space on macOS, investigate a near-full Mac, audit caches or developer artifacts, or create a repeatable Mac cleanup workflow. |
Mac Disk Cleanup
Use this skill to reclaim macOS disk space without accidental data loss.
The default workflow is: read-only audit, trusted-tool research, action table, explicit batch approval, cleanup, verification, and durable notes.
Safety Rules
- Do not run destructive commands until the user approves the exact batch.
- Treat user media, Documents, Downloads, browser profiles, app support data, secrets, project data, active worktrees, virtualenvs, Docker volumes, Photos libraries, and external-drive moves as protected by default.
- Do not use
/Volumes/* as an archive destination unless the user explicitly includes archive/offload scope.
- Ask narrowly for macOS privacy permissions only when a blocked path matters to an approved cleanup branch.
- Save one-off audit and cleanup scripts under the active task's
task-progress-artifacts/scratchpad/ before running them.
- Capture before/after evidence for every cleanup batch.
Read-Only Audit
Start with bounded checks:
df -h / /System/Volumes/Data /Volumes/* 2>/dev/null
tmutil listlocalsnapshots / 2>&1
du -sh "$HOME/.cache" "$HOME/.npm" "$HOME/Library/Caches" "$HOME/Library/Logs" "$HOME/Library/Developer" 2>&1
Then inspect likely candidates, keeping output bounded:
~/.cache children.~/Library/Caches children.~/Library/Logs children.~/Library/Developer/Xcode/DerivedData, Archives, iOS DeviceSupport.~/Library/Developer/CoreSimulator.- package-manager cache paths from owner commands.
- Docker state from
docker system df.
- selected project build artifacts such as
build, dist, .next, target, node_modules, .venv, and cache directories, without deleting them.
- user-facing folders such as Downloads/Documents only for size review.
Avoid broad recursive scans when the disk is critically low or macOS privacy blocks many subtrees.
Trusted Cleanup Mechanisms
Prefer owner commands over manual deletion:
- Homebrew:
brew cleanup --dry-run --prune=all before brew cleanup --prune=all.
- npm:
npm config get cache; npm cache clean --force only with approval.
- pnpm:
pnpm store path; pnpm store prune.
- uv:
uv cache dir; prefer uv cache prune over uv cache clean.
- pip:
pip3 cache info; pip3 cache purge.
- Docker:
docker system df; docker system prune -af only when volumes should be preserved.
- Xcode simulators:
xcrun simctl list devices unavailable; xcrun simctl delete unavailable only if useful.
For current behavior, check installed help (<tool> --help) and official docs when needed. Record what was reused, avoided, or adapted.
Action Table
Before cleanup, write an action table with:
- path or command
- size/evidence
- risk
- exact proposed action
- reversibility
- approval status
Recommended batch categories:
- High-dividend generated data: Docker unused images/build cache without volumes, Xcode DerivedData, large app logs.
- Smaller package caches: Homebrew, npm, pnpm, uv, pip.
- Developer project artifacts: generated build outputs and dependency directories, only after repo/worktree review.
- User-facing files: Downloads/Documents/media, only with path-level approval.
- Browser/app support data: usually defer; browser profiles are not cache.
Proven High-Dividend Pattern
On a near-full Mac, this approved batch reclaimed meaningful space:
docker system prune -af
rm -rf "$HOME/Library/Developer/Xcode/DerivedData"/*
rm -rf "$HOME/Library/Logs/activitywatch"
Important constraints:
- Do not add
--volumes to Docker prune unless the user explicitly approves volume deletion.
docker system prune -af removes stopped containers, unused networks, unused images, and build cache; images may need rebuild or re-pull later.- Xcode DerivedData is generated build data and will be recreated.
- Running apps may recreate log directories during deletion; verify final size rather than treating a tiny leftover log directory as failure.
Verification
After each approved batch:
df -h / /System/Volumes/Data
du -sh <approved-targets> 2>&1
docker system df 2>&1
Record:
- before and after free-space numbers
- command transcript
- target sizes before/after
- nonzero exit statuses and whether they are material
- skipped/deferred items
- recovery notes, such as "rebuild Docker image" or "Xcode will recreate DerivedData"
For tracked tasks, update status.md, save curated summaries under task-progress-artifacts/, and keep raw logs in task-progress-artifacts/scratchpad/.
