bmcreations/disk-jockey

Finds what is really eating your drive, then removes only what is provably safe.
---
Why this exists
AI agents work in parallel. Each task gets its own git worktree with its own full Gradle or Xcode build. Test runs clone simulators. Daemons, emulators and simulators stay up until memory spills into swap, and swap lives on the same disk.
On one real 1TB machine, free space went from **79G to 2.5G in twenty minutes**. The cause wasn't ~/Library/Caches:
- **17G of swap** from booted simulators, emulators and idle daemons (kernel_task had written 643GB)
- **37 forgotten agent worktrees** nested in repo/.claude/worktrees/, about 1 to 6G each
- **A staged macOS update** whose snapshots pinned every block deleted since
A generic "clear your caches" script finds none of that. disk-jockey checks for it first.
Quick start
That installs the latest release once for every agent and adds a disk-jockey command:
- ~/.agents/skills/disk-jockey is the copy Codex and Cursor read.
- ~/.claude/skills/disk-jockey links to it for Claude Code (a junction on Windows, so no Developer Mode needed).
- ~/.local/bin/disk-jockey is the command (~/bin in Git Bash). If that folder isn't on your PATH, the installer prints the line to add.
An existing clone in ~/.claude/skills is moved to the shared location rather than duplicated. Update with disk-jockey update; remove with bash ~/.agents/skills/disk-jockey/install.sh --uninstall.
Then tell your agent *"my disk is full"*, or drive it yourself:
Arrow keys move, space toggles, Enter continues. Every command takes --help.
Other ways to install
**Follow main instead of releases:**
**Manually, without the installer:**
Then run ~/.agents/skills/disk-jockey/bin/disk-jockey, or the scripts in scripts/ directly.
**claude.ai:** download disk-jockey-vX.Y.Z.zip from Releases and upload it as a custom skill.
**Pin a version:** bash install.sh --ref v0.2.0
See it work
**Interactive mode.** Arrow keys and space, like an installer. Safe caches are preselected, rebuild-cost items are one more press (or right arrow), and report-only data can't be selected at all. The worktree step works the same way: REMOVABLE worktrees start selected, and REVIEW ones (uncommitted or unpushed work) can be opted in after typing yes. Their commits stay on their branches; only uncommitted changes are discarded.
**Step one is always: is it really files?**
**Then the usual biggest win: agent worktrees.** Merged and clean ones go. Anything dirty, unpushed, recently touched or in use by a running agent stays.
How it works
| Script | What it does |
|---|---|
| dj.sh | Interactive mode for humans: one-key preflight fixes, arrow-key pickers for categories and worktrees, before/after summary |
| preflight.sh | Free space, load, swap, booted simulators, emulators, idle Gradle/Kotlin daemons, active builds, agent count, APFS snapshots, uptime |
| scan.sh | Sizes 90+ known targets across Xcode, simulators, Android, Gradle, Node, Python, Go, Rust, Flutter, Docker, editors, Electron apps, game engines and version managers |
| worktrees.sh | Audits every linked worktree, nested ones included. Detects squash-merged PRs with gh. --merged cleans up right after a merge |
| clean.sh | Tiered cleanup with the tools' own commands where they exist (simctl, brew cleanup, pnpm store prune) |
| sweep.sh | build/, .gradle, node_modules, target/, .build in projects idle for N days |
| schedule.sh | Daily tier-1 cleanup, only when free space drops below a threshold (launchd or systemd) |
| quarantine.sh | Opt-in undo: cleanup moves items aside for N days instead of deleting them |
| hooks.sh | Agent session hooks: shut down simulators and emulators that agent sessions booted |