vs-disk-cleanup
Free disk space left behind by coding agents: stale git worktrees (t3code, Codex, Claude Code), old vs session artifacts under ~/.vs, and home-folder dev leftovers. Removes only provably safe items and asks about the rest. Use when the user says /vs-disk-cleanup, cleanup/prune/remove worktrees, orphaned worktrees, clean ~/.vs, old vs reports or videos, out of disk space, disk full, no space left, free up space, or disk cleanup.
- License 许可
- MIT
- 所属仓库
- vltansky/vs
- 最近更新
- 2026-11-06
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- vs-disk-cleanup
- description
- Free disk space left behind by coding agents: stale git worktrees (t3code, Codex, Claude Code), old vs session artifacts under ~/.vs, and home-folder dev leftovers. Removes only provably safe items and asks about the rest. Use when the user says /vs-disk-cleanup, cleanup/prune/remove worktrees, orphaned worktrees, clean ~/.vs, old vs reports or videos, out of disk space, disk full, no space left, free up space, or disk cleanup.
02 资源文件 11
- 参考文档agents/openai.yaml88 B
- 脚本scripts/checks.sh3.5 KB
- 脚本scripts/disk-report/cleanup-script.mjs2.1 KB
- 脚本scripts/disk-report/cleanup.mts1.8 KB
- 脚本scripts/disk-report/scan.mts24.1 KB
- 脚本scripts/disk-report/template.html16.2 KB
- 脚本scripts/inventory.sh929 B
- 脚本scripts/remove.sh2.7 KB
- 脚本scripts/slim.sh1.3 KB
- 脚本scripts/vs-artifacts.sh4.9 KB
- 脚本test/disk-cleanup.static.eval.ts10.1 KB
03 SKILL.md 正文
Disk Cleanup
Agent worktrees and session artifacts pile up fast (tens of GB). Delete only what is recoverable; everything else is the user's call.
When running bundled scripts, first resolve this skill directory and use it as
$VS_DISK_CLEANUP_DIR. In this repository the source path is
skills/vs-disk-cleanup; in an installed agent runtime, use the installed
skill directory exposed by that runtime.
Report in the shape defined by
../vs-internal-shared/references/output-style.md.
Entry points
| User names | Start at |
|---|---|
| worktrees | step 1 |
~/.vs, vs reports, videos, artifacts |
step 3 |
| home folder, dev leftovers, disk space in general | step 6 (its report already covers worktrees and ~/.vs as review items) |
| plain "cleanup" | step 1, then 3; offer 4 and 6 only if space is still tight |
1. Inventory worktrees (read-only)
bash "$VS_DISK_CLEANUP_DIR/scripts/inventory.sh" > "<scratchpad>/wt.tsv"; df -h /System/Volumes/Data
- Options:
DAYS=7(idle threshold) andWT_ROOTS="dir1 dir2"(override the scanned roots). The script prints TSV columns:status path branch last_activity reason. - Use
/System/Volumes/Data, not/, for disk numbers on macOS. On APFS,/is the sealed system volume and its free-space figure is misleading. - It is slow because of
lsofand many repos. Run it with a long timeout (300s+) or in the background, and don't addduto the same command, sinceduover 70G times out.
| Status | Rule | Action |
|---|---|---|
SAFE |
no tracked changes, 0 commits missing from remotes, idle >= DAYS, no process cwd inside, untracked files are only junk (node_modules, build/, .playwright-mcp/, logs...), no gitignored secrets (.env*, keys) |
remove |
BUSY |
some process has its cwd inside | never touch |
RECENT |
last commit, or the newest changed or untracked non-junk file, within DAYS. The worktree root's own mtime doesn't count: any tool writing at the root bumps it | never touch |
DECIDE |
uncommitted changes, unpushed commits, real untracked files (ADRs, prototypes, docs, an uncommitted .vs/verify-map/), or gitignored secrets |
ask the user |
2. Remove the SAFE worktrees
If there are 0 SAFE rows, skip this step.
The user asking to "cleanup" counts as consent for SAFE rows only. Before removing anything, state the list you are about to remove.
awk -F'\t' '$1=="SAFE"{print $2}' "<scratchpad>/wt.tsv" | bash "$VS_DISK_CLEANUP_DIR/scripts/remove.sh"
remove.sh re-runs the full classification from checks.sh on each path and skips anything that is no longer SAFE, then runs git worktree remove --force. It then deletes the local branch, which stays recoverable from the remote, runs git worktree prune on each main repo, and prints the MB freed. Use it rather than hand-written rm, because removing the directory alone leaves the branch and the git metadata behind.
3. vs session artifacts (~/.vs)
vs skills write reports, videos, prototypes and evidence to ~/.vs/<project>/<kind>/. Most are one-session renderings; a few kinds are durable records later runs read back.
bash "$VS_DISK_CLEANUP_DIR/scripts/vs-artifacts.sh" > "<scratchpad>/vs.tsv"; du -sh ~/.vs
- Options:
DAYS=30(idle threshold, by newest file mtime) andVS_HOME(default~/.vs). TSV columns:status kb last_used path reason. - Render kinds are listed per entry, so one recent report doesn't shield stale ones beside it. All other kinds are listed as one row per kind dir.
| Status | Rule | Action |
|---|---|---|
STALE |
entry in a render kind (videos, vs-show-me, build-it, ship-it, qa-reports, prototypes, explanations, eli5, reviews, verification, pushback, steals, thread-analysis, briefs, vs-octocode, pr-<N>), idle >= DAYS |
move to Trash |
RECENT |
render-kind entry used within DAYS | never touch |
KEEP |
durable kind (specs, rfcs, issues, context, improve) or a regression baseline.json/baseline.png |
never offered |
REVIEW |
sessions/ handoffs, perf/ baselines, unknown kinds, loose files |
ask the user |
The user asking to clean ~/.vs (or a plain "cleanup") counts as consent for STALE rows only. State the count and total MB by kind, largest first, then run:
awk -F'\t' '$1=="STALE"{print $4}' "<scratchpad>/vs.tsv" | bash "$VS_DISK_CLEANUP_DIR/scripts/vs-artifacts.sh" --remove
--removere-classifies each path, refuses anything outside~/.vs/<project>/or notSTALEright now, and refuses a whole render-kind dir (it would sweep baselines). It moves entries to Trash (trash, else~/.Trash), then deletes the kind and project dirs left empty.- Say that space frees only after Trash is emptied, and never empty Trash yourself.
- Never delete
KEEProws. A spec or RFC is a decision record; losing it is not recoverable by re-running a skill.
4. Slim DECIDE worktrees (when disk is still tight)
node_modules, .cache and native build dirs make up most of a worktree's size. Deleting them keeps every commit, change and untracked file, so it needs no per-worktree approval. But they just rebuild, so propose it rather than doing it by default. Offer only worktrees idle for 14 days or more (DAYS=14 inventory), state the dry-run size, and run it on a yes:
awk -F'\t' '$1=="DECIDE"{print $2}' "<scratchpad>/wt.tsv" | bash "$VS_DISK_CLEANUP_DIR/scripts/slim.sh"
- Add
--dry-runto list the sizes without deleting anything. - The script deletes only paths that
git check-ignoreconfirms are ignored, and it skips worktrees that are BUSY. Never run it on RECENT or BUSY rows, because they may be in use. - Deleting millions of files takes more than 10 minutes. Always run it in the background, then wait for the final
deleted N dirs; freed:line. - Expect to free about half of what
--dry-run/dureports. pnpm hard-links files from its store, soducounts space that deleting doesn't free. SKIP not-ignored .../node_moduleslines are expected. Some repos commitnode_modulesas test fixtures.- Tell the user they need
pnpm install(or the repo's package manager) before working in a slimmed worktree again.
5. Report
- Report the MB freed and the free space before and after, plus MB moved to Trash from
~/.vs. - Show a table of
DECIDEworktrees grouped by reason (uncommitted N / unpushed N / untracked files / secrets), sorted by size, largest first. Measure them withdu -skon the DECIDE paths only. - Call out
unpushed=N (upstream gone, likely merged)rows separately. These branches were usually squash-merged, so they are the easiest ones to approve. The unpushed count uses local remote refs (nogit fetch), so it can be stale. - List
REVIEWrows from~/.vswith size and last used. - Offer options for
DECIDErows; don't act on them yet:- Save first, then remove:
... | bash "$VS_DISK_CLEANUP_DIR/scripts/remove.sh" --backup <dir>. For each DECIDE row it writes<dir>/<parent>-<name>.patch(git diff HEAD --binary) and.files.tgz(untracked files plus ignored secrets, nonode_modules). It then removes the worktree and keeps the local branch, so unpushed commits stay in the main repo. Without--backup, DECIDE rows are skipped. - Push the unpushed branch, then remove.
- Remove anyway: needs explicit user approval per group.
- Save first, then remove:
- If space is still tight, go to step 6 instead of ad-hoc
du.
6. Dev-leftovers report (beyond worktrees)
Read-only scan of the home folder: sizes only (du, stat mtimes), never file contents. It skips iCloud, Photos, external drives and TCC-protected folders (Desktop/Documents/Downloads, Mail, Messages, Safari, app Containers, Trash), so it raises no permission prompts.
node "$VS_DISK_CLEANUP_DIR/scripts/disk-report/scan.mts" # ~6 min; run in the background
- It reads
~/disk-report/sizes.csvfirst, then appends this scan's rows. It flags items that grew by at least 100 MB and 5% since the previous scan. Lead the report with those, excluded ones included: they explain where space goes even though they are never offered. - Reuse: if
~/disk-report/latest.jsonhas ascannedAtless than 1 hour old and nothing was deleted since, reuse it instead of rescanning. - It writes
~/disk-report/index.html: a treemap plus tables with path, size, last used and what happens if deleted. Ticking items there generatescleanup.sh. It also writes~/disk-report/latest.json, whichcleanup.mtsreads. - Grouping rules:
- Excluded, never offered: whole package-manager caches (npm, Yarn, pnpm, uv, pip, Gradle, CocoaPods, Cargo, Go, Bun, Homebrew, node-gyp, Electron). They refill on the next install. Also any safe item touched in the last 14 days (
ACTIVE_DAYS), meaning it is in use and would just rebuild. Both stay in the CSV for growth tracking. - Prune items, offered even while active: the stale parts of those caches.
pnpm store pruneanduv cache prune(drop only unreferenced entries, often a fraction of the size shown), npx envs unused 30+ days, Yarn Berry zips unused 60+ days, Gradle versions (cache plus wrapper) no build ran for 30+ days, the newest kept. Also Codex update leftovers older than a day:.codex/.tmp/marketplaces/.staging/*,marketplace-backup-*and.cache/codex-runtimes/codex-runtime-install-*. Codex never deletes these, and they reach tens of GB. - Let me review first: sessions, models and Docker always go here, along with worktrees,
~/.vsartifacts, simulators/AVDs, runtimes and unknown tools' caches. This group needs explicit per-item approval.- Colima: on each running profile, the clean command prunes stopped containers and unused images (
docker image prune -a), then runsfstrimin the VM. The VM disk is a sparse file, so a prune withoutfstrimfrees nothing on the Mac. Volumes are kept, and stopped profiles only get acolima delete <profile>suggestion. Before asking, list each profile's images withdocker --context colima[-<profile>] images. Images that were built locally can't be pulled again.
- Colima: on each running profile, the clean command prunes stopped containers and unused images (
- Safe to remove: stale, regenerable items (old project
node_modules/build dirs, Xcode DerivedData, iOS DeviceSupport).
- Excluded, never offered: whole package-manager caches (npm, Yarn, pnpm, uv, pip, Gradle, CocoaPods, Cargo, Go, Bun, Homebrew, node-gyp, Electron). They refill on the next install. Also any safe item touched in the last 14 days (
- To remove, first show the item list with sizes, taken from
latest.json. Once the user approves, generate the script with--yes(the y/N prompt would abort in a background run) and run it. Each item uses its tool's own clean command; the~/.vsitem runs step 3'svs-artifacts.shpipeline, never a whole-dir delete:node "$VS_DISK_CLEANUP_DIR/scripts/disk-report/cleanup.mts" --group safe --yes > "<scratchpad>/cleanup.sh" # or --ids a,b bash "<scratchpad>/cleanup.sh" # long: run in the backgroundrm_regen(safe items) deletes permanently, but inside a git repo it deletes only pathsgit check-ignoreconfirms, so committednode_modulesare skipped.rm_safe(review items) moves to Trash. Say that space frees only after Trash is emptied.- The script prints the MB freed. As with slim, expect less than
dureports because of pnpm hard links.
- Not dev, so not in the report:
~/Library/Application Support/com.apple.wallpaper(Aerial wallpapers, tens of GB). Mention it if space is critical.
Gotchas
git worktree removemust run from the main repo. The script resolves it viagit rev-parse --git-common-dir.--forcealso deletes gitignored files. That is why the inventory checksgit status --ignoredfor.env*and key files. It marks a worktree DECIDE only when such a file is missing from the main checkout or differs from it; byte-identical setup copies don't count.- An untracked
.vs/inside a worktree is not junk:.vs/verify-map/is committed source-of-truth, so an uncommitted one is real work. BUSYoften means an idle shell or agent left running. Point that out, but never kill processes.- Detached-HEAD worktrees with 0 unpushed commits count as SAFE because their commit is already on a remote.
- Paths under
~/.codex/worktrees/<id>/are left empty after removal.remove.shdeletes the empty parent dir.
Workflow
Direct: emit Next only. Composed: return to caller.
Prev: disk full | after a run of agent sessions Next: done Relevant: none
04 同仓库更多 Skills
vs-write
Use when asked to write, rewrite, edit, tighten, simplify, or polish prose for clarity, or to put text in STE, ASD-STE100, or controlled language. Produces plain, direct, accessible copy without losing substance or precision.
vs-fake-verify
暂无简介
vs-fake-verify
暂无简介
vs-verify
Use when asked to verify, prove it works, check completion, or before claiming done. Produces evidence-backed PASS/WARN/FAIL status.
vs-fake-verify
暂无简介
vs-verify
Use when asked to verify, prove it works, check completion, or before claiming done. Produces evidence-backed PASS/WARN/FAIL status.