disk-cleanup, get the disk back from your agents
Running many agents and worktrees fills a disk fast: a fresh node_modules per
worktree, a build cache per tool, Docker layers, browser downloads, session logs.
This skill finds all of it, sorts it by how safe it is to remove, and removes only
what is provably safe, after you confirm.
Critical rules
- Dry run first, always. Run the script without
--apply, show the inventory, and
get an explicit yes from the user in the conversation before any --apply.
--apply touches two tiers only. SAFE (caches that refill on their own) and
REGENERABLE (merged, clean, idle worktrees; rebuildable stores). ASK FIRST items are
listed with the command to run. The script never runs them and neither do you without
the user naming the item.
- Unreadable is KEEP. A failed
git, gh, lsof or docker call keeps the item and says why.
Never remove on a guess.
- A worktree is removed only when all of these hold: its tip is on the default branch
(or equals the head of a merged PR), the tree is clean, it holds no ignored file outside
a rebuildable folder (
node_modules, .venv, dist, build, .next, __pycache__ and
the like; an ignored .env.local keeps the tree), it is not locked, no process has
its working directory inside, nothing in it changed for 60 minutes, and it sits under
the home directory. Removal is git worktree remove without force. The branch stays.
- Report the measured number. The freed total is free space before versus after. The
inventory total is an estimate and is labelled as one.
Instructions
Dry run. From a repo you work in (the script scans its worktrees) or with --root DIR
for a folder that holds several repos:
python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py"
python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py" --root ~/code
Exit 0 means nothing to clean, 3 means findings, 2 means it could not look.
Show the user the inventory as printed. Lead with the verdict line, then name the three
biggest rows and any KEEP lines that explain why a worktree was left alone.
Ask the user to confirm. Offer the narrower forms when they hesitate:
--tier safe (caches only) or --only npm-cache (one item id, or a section such as docker).
Apply with the command the dry run printed under "To act on exactly this list". It
pins --only to the ids the user just saw, so anything that became removable after
the dry run (a worktree that merged or went idle meanwhile) is left alone:
python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py" --apply --only npm-cache --only 'worktree:/path/to/tree'
python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py" --apply --tier safe
Expected: one line per action (done or failed), then freed (measured, before and after).
For ASK FIRST rows, read the user the printed command and what it removes. Run it only
when they confirm that specific row.
Optional: --json for a machine-readable inventory, --report FILE to save it. The report
starts with a marker line and the script refuses to overwrite a file without it.
What counts as what
| Tier |
Meaning |
Examples |
| 🟢 SAFE |
Pure cache, the tool refills it |
npm, pip, uv, Cargo, Go caches, Homebrew downloads, Xcode DerivedData, browser caches, Docker build cache and dangling images, agent debug logs older than 14 days |
| 🟡 REGENERABLE |
Rebuilds, but costs time or bandwidth |
merged worktrees, pnpm store, Playwright browsers, unused Docker images |
| 🔴 ASK FIRST |
Might be someone's work |
unmerged or detached worktrees, session transcripts, Downloads, Trash, Docker volumes, orphan agent processes |
Full path list per OS and the evidence behind each gate: references/catalog.md.
Example output
disk-cleanup dry run: 47.1 G reclaimable, 24.0 G more needs you
DISK ~ (macOS)
[▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░]
used 355.0 G free 73.0 G 83 % full · 460.0 G total
────────────────────────────────────────────────────────────────────────
🟢 SAFE caches that refill on their own
────────────────────────────────────────────────────────────────────────
🐳 Docker build cache ▓▓▓▓▓▓▓ 14.5 G prune
🌐 Browser caches ▓▓▓▓░░░ 8.9 G clear
📦 npm cache ▓▓▓░░░░ 6.2 G clear
── 29.6 G
────────────────────────────────────────────────────────────────────────
🟡 REGENERABLE merged worktrees and rebuildable stores
────────────────────────────────────────────────────────────────────────
🗂️ app/fix-login merged PR #412 ▓▓▓▓░░░ 3.9 G remove
KEEP app/hotfix-7 dirty (3 files)
KEEP app/agent-3 process cwd inside (pid 4121)
🟢 29.6 G + 🟡 3.9 G = 33.5 G estimated → free 73.0 G → ~106.5 G
ℹ️ Sizes are allocated blocks, so sparse files read small.
Examples
User says: "my disk is almost full, I run a lot of agents".
Actions: run the dry run, show the inventory, ask to confirm, run --apply.
Result: SAFE and REGENERABLE items removed, a measured freed total, ASK FIRST rows left for the user.
User says: "clean up old worktrees only".
Actions: dry run, then --apply --only worktrees after confirmation.
Result: merged clean worktrees removed, everything else untouched.
Troubleshooting
| Symptom |
Cause |
Fix |
| Every worktree reads KEEP "process list unreadable" |
lsof missing or blocked (some sandboxes) |
Run the script outside the sandbox, or install lsof. Never skip the check. |
| Squash-merged worktrees read as unmerged |
gh missing or not logged in |
gh auth login, then rerun. They stay ASK FIRST until then. |
| Docker items missing |
Docker daemon not running |
Start Docker and rerun. The caveat line says so. |
| Freed total is smaller than the estimate |
Docker Desktop keeps its disk image at full size, APFS snapshots hold blocks |
Trust the measured number. Compact Docker Desktop's disk image from its settings. |
git worktree remove refused |
The tree changed between the dry run and --apply |
Rerun the dry run. It will classify the tree again. |
Audit trail
Every applied action appends one JSON line to ~/.local/state/ork/disk-cleanup-ledger.jsonl
(override with --ledger), plus one summary line per run.
Scope
macOS first, Linux second. Windows is not supported. The skill frees disk space only:
it does not stop sessions, delete branches, or touch anything outside the home directory.
Related Skills
ork:dev: stop a branch's dev loop before its worktree is removed.
ork:doctor: project and plugin health, the other maintenance check next to disk space.
ork:careful: guard destructive shell commands while a cleanup runs.
1---2name: disk-cleanup3compatibility: "Claude Code 2.1.277+. macOS or Linux, Python 3.9+, git. Optional: gh, docker, lsof."4description: "Frees the disk that agents and worktrees leave behind: caches, merged worktrees, Docker build cache, old logs. Dry run lists safe, regenerable and ask-first items with sizes; --apply after you confirm. Use when the disk is nearly full. Never deletes branches."5license: MIT6argument-hint: "[--apply] [--only ID] [--tier safe|regenerable] [--root DIR] [--json]"7user-invocable: true8disable-model-invocation: false9effort: low10allowed-tools: Bash, Read, AskUserQuestion11metadata:12 source: https://skillmd.com/skills/yonatangross/disk-cleanup13 category: devops14 version: "1.0.0"15 author: "OrchestKit"16 complexity: "low"17 tags: "disk, cleanup, worktrees, caches, docker, agents, macos, linux"18---1920# disk-cleanup, get the disk back from your agents2122Running many agents and worktrees fills a disk fast: a fresh `node_modules` per23worktree, a build cache per tool, Docker layers, browser downloads, session logs.24This skill finds all of it, sorts it by how safe it is to remove, and removes only25what is provably safe, after you confirm.2627## Critical rules28291. **Dry run first, always.** Run the script without `--apply`, show the inventory, and30 get an explicit yes from the user in the conversation before any `--apply`.312. **`--apply` touches two tiers only.** SAFE (caches that refill on their own) and32 REGENERABLE (merged, clean, idle worktrees; rebuildable stores). ASK FIRST items are33 listed with the command to run. The script never runs them and neither do you without34 the user naming the item.353. **Unreadable is KEEP.** A failed `git`, `gh`, `lsof` or `docker` call keeps the item and says why.36 Never remove on a guess.374. **A worktree is removed only when all of these hold:** its tip is on the default branch38 (or equals the head of a merged PR), the tree is clean, it holds no ignored file outside39 a rebuildable folder (`node_modules`, `.venv`, `dist`, `build`, `.next`, `__pycache__` and40 the like; an ignored `.env.local` keeps the tree), it is not locked, no process has41 its working directory inside, nothing in it changed for 60 minutes, and it sits under42 the home directory. Removal is `git worktree remove` without force. The branch stays.435. **Report the measured number.** The freed total is free space before versus after. The44 inventory total is an estimate and is labelled as one.4546## Instructions47481. Dry run. From a repo you work in (the script scans its worktrees) or with `--root DIR`49 for a folder that holds several repos:5051 ```bash52 python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py"53 python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py" --root ~/code54 ```5556 Exit 0 means nothing to clean, 3 means findings, 2 means it could not look.572. Show the user the inventory as printed. Lead with the verdict line, then name the three58 biggest rows and any KEEP lines that explain why a worktree was left alone.593. Ask the user to confirm. Offer the narrower forms when they hesitate:60 `--tier safe` (caches only) or `--only npm-cache` (one item id, or a section such as `docker`).614. Apply with the command the dry run printed under "To act on exactly this list". It62 pins `--only` to the ids the user just saw, so anything that became removable after63 the dry run (a worktree that merged or went idle meanwhile) is left alone:6465 ```bash66 python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py" --apply --only npm-cache --only 'worktree:/path/to/tree'67 python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py" --apply --tier safe68 ```6970 Expected: one line per action (done or failed), then `freed (measured, before and after)`.715. For ASK FIRST rows, read the user the printed command and what it removes. Run it only72 when they confirm that specific row.736. Optional: `--json` for a machine-readable inventory, `--report FILE` to save it. The report74 starts with a marker line and the script refuses to overwrite a file without it.7576## What counts as what7778| Tier | Meaning | Examples |79|---|---|---|80| 🟢 SAFE | Pure cache, the tool refills it | npm, pip, uv, Cargo, Go caches, Homebrew downloads, Xcode DerivedData, browser caches, Docker build cache and dangling images, agent debug logs older than 14 days |81| 🟡 REGENERABLE | Rebuilds, but costs time or bandwidth | merged worktrees, pnpm store, Playwright browsers, unused Docker images |82| 🔴 ASK FIRST | Might be someone's work | unmerged or detached worktrees, session transcripts, Downloads, Trash, Docker volumes, orphan agent processes |8384Full path list per OS and the evidence behind each gate: `references/catalog.md`.8586## Example output8788```text89disk-cleanup dry run: 47.1 G reclaimable, 24.0 G more needs you9091DISK ~ (macOS)92[▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░]93 used 355.0 G free 73.0 G 83 % full · 460.0 G total94────────────────────────────────────────────────────────────────────────95🟢 SAFE caches that refill on their own96────────────────────────────────────────────────────────────────────────97🐳 Docker build cache ▓▓▓▓▓▓▓ 14.5 G prune98🌐 Browser caches ▓▓▓▓░░░ 8.9 G clear99📦 npm cache ▓▓▓░░░░ 6.2 G clear100 ── 29.6 G101────────────────────────────────────────────────────────────────────────102🟡 REGENERABLE merged worktrees and rebuildable stores103────────────────────────────────────────────────────────────────────────104🗂️ app/fix-login merged PR #412 ▓▓▓▓░░░ 3.9 G remove105 KEEP app/hotfix-7 dirty (3 files)106 KEEP app/agent-3 process cwd inside (pid 4121)107🟢 29.6 G + 🟡 3.9 G = 33.5 G estimated → free 73.0 G → ~106.5 G108ℹ️ Sizes are allocated blocks, so sparse files read small.109```110111## Examples112113User says: "my disk is almost full, I run a lot of agents".114Actions: run the dry run, show the inventory, ask to confirm, run `--apply`.115Result: SAFE and REGENERABLE items removed, a measured freed total, ASK FIRST rows left for the user.116117User says: "clean up old worktrees only".118Actions: dry run, then `--apply --only worktrees` after confirmation.119Result: merged clean worktrees removed, everything else untouched.120121## Troubleshooting122123| Symptom | Cause | Fix |124|---|---|---|125| Every worktree reads KEEP "process list unreadable" | `lsof` missing or blocked (some sandboxes) | Run the script outside the sandbox, or install `lsof`. Never skip the check. |126| Squash-merged worktrees read as unmerged | `gh` missing or not logged in | `gh auth login`, then rerun. They stay ASK FIRST until then. |127| Docker items missing | Docker daemon not running | Start Docker and rerun. The caveat line says so. |128| Freed total is smaller than the estimate | Docker Desktop keeps its disk image at full size, APFS snapshots hold blocks | Trust the measured number. Compact Docker Desktop's disk image from its settings. |129| `git worktree remove` refused | The tree changed between the dry run and `--apply` | Rerun the dry run. It will classify the tree again. |130131## Audit trail132133Every applied action appends one JSON line to `~/.local/state/ork/disk-cleanup-ledger.jsonl`134(override with `--ledger`), plus one summary line per run.135136## Scope137138macOS first, Linux second. Windows is not supported. The skill frees disk space only:139it does not stop sessions, delete branches, or touch anything outside the home directory.140141## Related Skills142143- `ork:dev`: stop a branch's dev loop before its worktree is removed.144- `ork:doctor`: project and plugin health, the other maintenance check next to disk space.145- `ork:careful`: guard destructive shell commands while a cleanup runs.