scan
/scan
Break down how much space a project folder or directory uses and which of it can be safely reclaimed (node_modules, build output, caches, logs, git worktrees). Use when asked why a folder or project is huge, how to free up space in it, or whether something in it is safe to delete. Read-only; never deletes without confirmation; git-aware. For the whole machine, use /disk-reclaim:system.
- Author
- jwill824 ↗
- Repository
- claude-plugins ↗
- Licence
- MIT
- Last repository change
- 05.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Break down how much space a project folder or directory uses and which of it can be safely reclaimed (node_modules, build output, caches, logs, git worktrees). Use when asked why a folder or project is huge, how to free up space in it, or whether something in it is safe to delete. Read-only; never deletes without confirmation; git-aware. For the whole machine, use /disk-reclaim:system.
Arguments
/scan [DIR]
Original author description
Break down how much space a project folder or directory uses and which of it can be safely reclaimed (node_modules, build output, caches, logs, git worktrees). Use when asked why a folder or project is huge, how to free up space in it, or whether something in it is safe to delete. Read-only; never deletes without confirmation; git-aware. For the whole machine, use /disk-reclaim:system.
How it works
- 1. Run the scanner
- 2. Read the result, then add judgment
- 3. Purging SAFE items (the built-in purge option)
- 4. Other deletions (only after the user says yes)
- Notes
SKILL.md preview
---
name: scan
description: Break down how much space a project folder or directory uses and which of it can be safely reclaimed (node_modules, build output, caches, logs, git worktrees). Use when asked why a folder or project is huge, how to free up space in it, or whether something in it is safe to delete. Read-only; never deletes without confirmation; git-aware. For the whole machine, use /disk-reclaim:system.
argument-hint: "[DIR]"
---
# scan
Plugin root: `${CLAUDE_PLUGIN_ROOT}`. Scripts are in `${CLAUDE_PLUGIN_ROOT}/scripts/`; shared guidance is in `${CLAUDE_PLUGIN_ROOT}/references/`.
Scan the directory in `$ARGUMENTS` (default: the current directory). Answer two questions: **where is the space going**, and **what can be given back without losing anything that cannot be rebuilt**. Analysis is read-only. Deleting is a separate, confirmed step.
**Non-negotiables** (full text in `${CLAUDE_PLUGIN_ROOT}/references/deletion-rules.md`, read it before removing anything):
- Show a dry run first. Remove nothing until the user has approved the items by name.
- Re-check each item immediately before it runs; skip and report any that changed.
- Prefer reversible actions. Never use `--force`, `git clean -x` or `git reset --hard`, and never delete branches, unless the user asks for that exact thing.
- Never propose KEEP items, and never promote a VERIFY item because it is old.
## 1. Run the scanner
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/scan.py [DIR] [--top 15] [--min-mb 20] [--max-depth 6]
```
`DIR` defaults to the current directory. It prints markdown: largest subdirectories, reclaimable items grouped by safety tier and category, git worktrees, large files, and proposed (not executed) commands. Add `--json` if you need to post-process, `--min-mb 0 --top 200` to see small items.
On a very large tree the scan can take a few minutes (it honours `--max-seconds` and says so if it stopped early). If the user points it at a home directory or `/`, narrow it first (for example the projects folder) because a whole-disk scan mostly finds things nobody wants removed.
## 2. Read the result, then add judgment
The script classifies; you decide what to say. Present a short summary first (total, free space, the few biggest wins), then the tables. Keep it compact: sizes human-readable, top N only.
Read `${CLAUDE_PLUGIN_ROOT}/references/tiers-and-gates.md` for what SAFE, VERIFY and KEEP mean and how to treat each. If the result looks surprising (a "SAFE" item you doubt, a huge KEEP), check it yourself rather than repeating the label.
## 3. Purging SAFE items (the built-in purge option)
After the report, offer to purge the SAFE items. Ask which categories (build caches, build output, dependency caches) and confirm the policy, because it is a judgment about the user's workflow, not a fact: by default the purge keeps build output in **high-traffic checkouts** (a normal clone, and any worktree named `main`) so they stay ready to build and run, and clears the same output from linked worktrees and other low-traffic copies, where it only takes up space.
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/scan.py DIR --json > /tmp/scan.json
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/reclaim.py /tmp/scan.json --categories "build cache,build output" --exclude some/path # dry run
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/reclaim.py /tmp/scan.json --categories "build cache,build output" --exclude some/path --execute
```
`reclaim.py` is a dry run unless `--execute` is given. It re-verifies every item at that moment (still git-ignored, no tracked files, no key material, manifest beside it), skips any checkout with a process running in it, removes only directories with known derived-output names, writes a log, and reports the free space gained. Always show the user the dry-run table first, and exclude any single item they are unsure of (a huge `build/` folder can be a packaged deliverable). Use `--no-protect` only if the user asks to clear the high-traffic checkouts too.
## 4. Other deletions (only after the user says yes)
Read `${CLAUDE_PLUGIN_ROOT}/references/deletion-rules.md` and follow it: show the exact commands and the space they free, re-check just before acting, prefer reversible actions, and report what was removed, what was skipped and why.
## Notes
- Sizes are block usage from `du`; hard-linked or copy-on-write files (pnpm stores, APFS clones) can make real savings smaller.
- Works on macOS and Linux with no configuration and no paths baked in. Standard library Python 3 only; needs `du`, and `git` for the repository-aware checks.
- **This tool deletes data** once `reclaim.py --execute` is given, after the dry run and the user's approval. Provided as is, without warranty (MIT licence).
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · jwill824/claude-plugins | 100 | MIT |
| tony/skills | 100 | MIT |
| zealynxsecurity/krait | 100 | MIT |
| koda-ai-studio/agent-bom | 100 | Apache-2.0 |
| cwinvestments/memstack | 100 | MIT |
| x-cmd/x-cmd | 100 | Apache-2.0 |
| duc01226/EasyPlatform | 100 | MIT |
| duc01226/EasyPlatform | 100 | MIT |
| wshobson/agents | 100 | MIT |
Database snapshot: 13.11.2026 · package version 894b6b368efa (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90free-up-disk-space
Free up disk space on the user's Mac safely with DiskSpace AI. Use when the user says their Mac or disk is full, asks what's taking up space, can't install a macOS update, wants to clean caches, Xcode DerivedData, simulators, Docker, node_modules or AI models, or asks whether a… - 100cleanup
Free up disk space on this computer: list what takes space with its size, why it is safe to delete and what it costs, then delete only what the owner picks. Use when someone says "cleanup", "clean up disk", "free up space", "my disk is full", "out of space", "the Mac is full",… - 100safe-disk-cleanup
Safely diagnose and reclaim disk space on developer machines with explainable deletion decisions, deep read-only inventory, worktree and Docker auditing, active-tool guards, and file-level dry-runs. Use when a disk is full, storage is low, developer resources are large, or the… - 100pro-disk-cleanup
Find and clear reclaimable disk space safely on any macOS, Windows or Linux machine and stack: read-only scan, three tiers (safe, decide, keep), closed-issue worktrees with backup, build output, caches, Docker. Use for 'disk is full', 'free up space'. - 100mac-storage-cleaner
Safely reclaim disk space on a Mac — the trustworthy, transparent, reversible alternative to CleanMyMac and similar tools. Use whenever the user says their Mac disk or storage is full or nearly full, gets a "startup disk almost full" / low-storage warning, asks to free up space,… - 100mac-storage-saver
Find what is using disk space on a Mac and free it safely. Scans the disk read-only, sorts every large folder into safe to clean, reinstall needed, your call and don't touch, builds an HTML report with an approval checklist, then deletes only the items the user approves. Use…