| name | clean-storage |
| description | Reclaims disk space by finding and removing regenerable build artifacts and tool caches (cargo target/, Xcode DerivedData, node_modules, Swift .build, Homebrew/pnpm/bun/npm caches). Triggers on "clean storage", "free up disk space", "what is taking up space", "disk is full", "reclaim disk", "clean build artifacts", "clear caches", or invokes /clean-storage. |
| disable-model-invocation | true |
| effort | high |
Clean storage
Finds regenerable build artifacts and caches, verifies each one is genuinely
disposable, reports them, and cleans only after the user agrees. Cargo projects are
cleaned through cargo clean; other verified artifacts are deleted directly.
Do not add context: fork. This workflow depends on AskUserQuestion for the
deletion checkpoint and on the user reading the full path list, and a forked
subagent cannot prompt the user. It must run inline.
Workflow
1. Scan (read-only, run without asking)
bun $SKILL_DIR/scripts/scan.ts --root ~/Code --root ~/Projects
Default root is the home directory. Scanning a whole home directory takes a while,
so prefer explicit --root flags when the user named a location.
Useful flags:
| Flag | Effect |
|---|
--root <path> | Root to walk, repeatable. Default ~ |
--min-size <MB> | Hide candidates below this size. Default 10 |
--max-depth <n> | Walk depth. Default 8 |
--caches | Add global caches to a root-scoped scan |
--json | Machine-readable output |
--apply | Delete the verified candidates |
Global caches (Xcode DerivedData, DeviceSupport, go-build, Playwright, and the
package manager stores) live outside any scanned root. They are included only in a
home-wide scan, or when --caches is passed. This keeps a scoped request like
"clean up my Rust project" from proposing deletions across the whole machine.
2. Report every path and action
Print the complete list of artifacts that would be cleaned, one per line, before
asking for anything. Include the scanner's action for every path: Cargo targets
show the project directory where cargo clean will run; other artifacts show
delete. The user is authorizing specific paths and actions, not a number. A
category summary alone is not enough to consent to a deletion, and neither is "the
largest few entries".
The script already prints the full list under "Will clean". Relay it verbatim. Do
not truncate it, do not replace it with the category totals, and do not collapse it
to the top N. If the list is long, that is information the user needs: a 153-entry
list is itself a signal about how wide the deletion is.
Then also surface:
- Anything under "Skipped", with its reason. These are candidates the scanner could
not prove regenerable, and they are worth a human glance.
- The category totals and grand total, after the full list, as a summary.
- The tool-managed cache commands, which the script never runs itself.
3. Confirm before deleting
Cleanup is destructive. Use AskUserQuestion to confirm, only after the full path
list is on screen. Include the total and the category breakdown in the question so
the user is deciding on real numbers.
Never run --apply without an explicit yes in the conversation. A general request
like "clean up my disk" authorizes the scan, not the deletion.
4. Apply
bun $SKILL_DIR/scripts/scan.ts --root ~/Code --apply
Pass the same roots and filters used for the scan, so the user approves the same set
that gets deleted.
The script refuses to run --apply while a build process is detected, since cleaning
build output during a build corrupts or invalidates it. If it refuses, report which
process blocked it rather than working around the check.
For every verified Cargo target, apply mode runs cargo clean with the sibling
Cargo.toml directory as its working directory. It never directly removes a Cargo
target/ directory. This preserves Cargo's ownership of its artifacts and respects
project-specific Cargo configuration.
5. Report the outcome
Give the before and after free space and the count actually cleaned. If any path
failed, say which and why.
Safety model
Discovery is by directory name, which proves nothing on its own. Every candidate must
pass an independent check before it is eligible, and it is re-verified immediately
before deletion so a stale scan cannot widen the blast radius.
| Category | Proof |
|---|
cargo | contains CACHEDIR.TAG and has sibling Cargo.toml |
xcode | git check-ignore passes |
node-modules | sibling package.json |
swift | sibling Package.swift |
cache | known fixed cache path |
Two exclusions run first and override the proof above:
- Installed software (
~/.bun/install/global, ~/.local/share/mise, /usr/local/lib/node_modules,
and similar). A globally installed CLI has a node_modules beside a package.json,
so the proof alone would green-light uninstalling every global package.
- Tool-managed caches (
~/.bun/install/cache, ~/Library/pnpm/store, and similar).
These are reported with the vendor command instead, so they are not also deleted piecemeal.
Cargo is also tool-managed at the project level: verified target/ directories are
reported by size, but apply mode invokes cargo clean in each owning project rather
than calling the filesystem deletion API.
Anything that fails is reported and skipped, never deleted. The scanner is built to
under-report rather than over-delete.
User data is out of scope. Messages attachments, ~/Downloads, Photos libraries, and
Simulator devices are never touched, even when large.
See references/categories.md for the full category list,
the reasoning behind each proof, and walk behavior.
Notes
- The user's environment may block
rm -rf from the agent. The script deletes through
Bun's filesystem API rather than shelling out, but if a permission prompt appears,
let the user answer it instead of finding another route.
- Deleting these directories costs a cold rebuild on next build. Mention this when the
reclaimed set is dominated by projects the user is actively working in.
