Why this exists
My working vault once hit 325,000 files. The actual work was maybe a tenth of that; the rest was node_modules in abandoned experiments, Python caches, nested zip backups of folders that still existed, and seventeen variations of _backup_final. Finding out took an evening. Deciding what was safe to remove took longer, because nothing is scarier than deleting in bulk from a folder that contains your real work.
That cleanup (325k files down to 33k) became this skill. The design principle came straight from the experience: the scan is easy, the trust is hard. So it reports first, groups everything by how regenerable it is, flags the ambiguous cases instead of recommending them, and even when you approve a cleanup it prefers moving things to a dated archive over hard deletion.
How it works
- It scans without touching One folder tree, read-only. Files are classified into groups: dependency folders, build caches, backup litter, logs, OS litter, and lone heavyweight files over 100 MB.
- It knows what is never junk Live git repos, .env files, anything named with clear intent to keep, and anything that looks like the only copy of created work (documents, designs, photos). Those get flagged, never recommended for deletion.
- It reports in order of confidence A cleanup-report.md with headline numbers, per-group sizes, the top offenders, and recommendations sorted by most space per least risk. Regenerable caches lead; ambiguous backups come last with a verify-first flag.
- It cleans only your approved list You name the groups or paths. It moves them to a dated archive (or recycle bin) rather than hard-deleting, confirms the exact list once, then re-reports the numbers so the result is visible.
Step by step (for first-time users)
- Open Claude Code in the messy folder Your projects directory, your downloads, the client-work drive you have not looked at since 2024.
-
Type
/vault-janitorThe scan runs read-only. Nothing changes yet. - Read cleanup-report.md Headline numbers first: total files, total size, and how much of it is regenerable junk. Then per group, biggest offenders first.
- Approve a list, starting with the safe groups Dependency folders and caches are regenerable by definition: biggest win, lowest risk. Leave the flagged items for a second pass when you can check them.
- Check the after-numbers The re-scan shows what changed. Archived items sit in a dated folder until you are confident, then you empty it on your own schedule.
What gets flagged vs recommended
| Finding | Treatment |
|---|---|
| node_modules in a project untouched for a year | Recommended: regenerable with one install command |
| __pycache__, .cache, build output | Recommended: regenerable by definition |
| backup.zip with no matching folder anywhere | Flagged: might be the only copy, verify before touching |
| "backup" folder edited last week | Flagged: recent edits suggest it is in use |
| .env, live .git, folders named with intent to keep | Never touched, not even suggested |
Honest take
What it does well: The grouping and the restraint. Sorting junk by "how regenerable is this" turns a scary bulk deletion into a sequence of obviously safe decisions, and the archive-first default means even a wrong call is reversible for as long as you keep the archive. The judgment-call flags are the part born from real experience: pattern-matching says a folder named backup is junk; the file dates sometimes say otherwise.
What it does not do: It does not run unattended, does not clean whole drives in one sweep, and does not read your file contents (it judges by names, sizes, and dates). It also warns rather than acts inside OneDrive and other sync folders, because a deletion there propagates to every device. If you want a fully automatic cleaner, this is deliberately not that.
When to use it: When a folder feels heavy and you do not know why. Before backing up or migrating a machine (no point archiving 200,000 cache files). And quarterly on any directory where projects go to be forgotten.