Skip to content
Skills Library
DevOps & cloud · Automation

disk-cleanup

/disk-cleanup

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.

Repository
orchestkit ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/disk_cleanup.py

What it does and when to use it

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.

Arguments

/disk-cleanup [--apply] [--only ID] [--tier safe|regenerable] [--root DIR] [--json]
Original author description

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.

How it works

  1. Critical rules
  2. Instructions
  3. What counts as what
  4. Example output
  5. Examples
  6. Troubleshooting
  7. Audit trail
  8. Scope
  9. Related Skills
Original SKILL.md headings · 128 lines, 1,050 words
SKILL.md preview
---
name: disk-cleanup
compatibility: "Claude Code 2.1.277+. macOS or Linux, Python 3.9+, git. Optional: gh, docker, lsof."
description: "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."
license: MIT
argument-hint: "[--apply] [--only ID] [--tier safe|regenerable] [--root DIR] [--json]"
user-invocable: true
disable-model-invocation: false
effort: low
allowed-tools: Bash, Read, AskUserQuestion
metadata:
  category: devops
  version: "1.0.0"
  author: "OrchestKit"
  complexity: "low"
  tags: "disk, cleanup, worktrees, caches, docker, agents, macos, linux"
---

# 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

1. **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`.
2. **`--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.
3. **Unreadable is KEEP.** A failed `git`, `gh`, `lsof` or `docker` call keeps the item and says why.
   Never remove on a guess.
4. **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.
5. **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

1. Dry run. From a repo you work in (the script scans its worktrees) or with `--root DIR`
   for a folder that holds several repos:

   ```bash
   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.
2. 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.
3. 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`).
4. 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:

   ```bash
   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)`.
5. For ASK FIRST rows, read the user the printed command and what it removes. Run it only
   when they confirm that specific row.
6. 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

```text
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.
Files in this package (4)
  • SKILL.md 8 KB
  • test-cases.json 2 KB
  • references/catalog.md 4 KB
  • scripts/disk_cleanup.py 42 KB

Versions

RepositoryScoreLicence
This page · yonatangross/orchestkit100MIT
glebis/claude-skills100MIT
inline-chat/inline100AGPL-3.0
hakula139/plugins100MIT
moonlight-lupin/agent-skills100MIT
mtarcure/claude-vibe-squad100MIT
DaraBoth/skilljmskill98MIT
sasugadayo/disk-cleanup-skill98MIT
SamueleGuerrini/disk-cleanup-skill93MIT

Database snapshot: 13.11.2026 · package version 79881a2727e7 (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

  • 100cleanup
    Reclaim disk space and prune branches left behind by AI coding agents - merged or abandoned git worktrees, merged branches, stale build artifacts (node_modules, .venv, target), old archives and backups, package caches, and old agent session logs. Use when the user runs /cleanup,…
  • 86cleanup
    Free disk in a project by removing the git worktrees and Next.js cache folders nothing uses, keeping every worktree a session or process works in and every cache a running server holds. Use for /cleanup, \"clean up worktrees\", \"free disk space\", \"what's using my disk\",…
  • 81cleanup
    Free disk in a project by removing the git worktrees and Next.js cache folders nothing uses, keeping every worktree a session or process works in and every cache a running server holds. Use for /cleanup, \"clean up worktrees\", \"free disk space\", \"what's using my disk\",…
  • 100cleanup-worktree-disk
    Reclaim macOS disk space by removing git worktrees whose PRs are already merged (plus their branches and Bazel output bases) and by deleting orphaned Bazel output bases whose workspace directory no longer exists. Use whenever the user is low on disk, says "clean up disk space",…
  • 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'.
  • 100clean-dev-caches
    Free disk space on a developer machine by clearing regenerable caches (npm, Bun, Yarn, pnpm, Homebrew, pip, uv, Go, Gradle, CocoaPods, Xcode DerivedData, old Playwright/Puppeteer browsers, VS Code and JetBrains caches, Docker build cache), stale project build outputs (.next,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.