reclaim-disk-space
Skill4 starsChanged 50 days agoMITView on GitHub
Audit and reclaim disk space cautiously on a development Mac, especially when storage is nearly full, caches and build artifacts have accumulated, or a Git repository has many temporary worktrees. Use for disk-usage investigation, cleanup planning, cache pruning, and explicitly requested deletion. Separates reproducible data from user state, verifies Git worktrees are registered, clean, and merged, and reports exact targets, recovery risk, and measured space before and after.
In this repository48 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/skills/AGENTS.mdAGENTS.md
- .agents/skills/assumption-audit/AGENTS.mdAGENTS.md
- .agents/skills/decision-matrix/AGENTS.mdAGENTS.md
- .agents/skills/direct-setup/AGENTS.mdAGENTS.md
- .agents/skills/direct-verify/AGENTS.mdAGENTS.md
- .agents/skills/first-principles-thinking/AGENTS.mdAGENTS.md
- .agents/skills/percolate-kb/AGENTS.mdAGENTS.md
- .agents/skills/percolate-reading/AGENTS.mdAGENTS.md
- .agents/skills/phase-final-reviewer/AGENTS.mdAGENTS.md
- .agents/skills/phase-implementer/AGENTS.mdAGENTS.md
- .agents/skills/phase-orchestrator/AGENTS.mdAGENTS.md
- .agents/skills/phase-reviewer/AGENTS.mdAGENTS.md
- .agents/skills/plan-kb/AGENTS.mdAGENTS.md
- .agents/skills/pr-cleanup/AGENTS.mdAGENTS.md
- .agents/skills/query-kb/AGENTS.mdAGENTS.md
- .agents/skills/question-forge/AGENTS.mdAGENTS.md
- .agents/skills/reclaim-disk-space/AGENTS.mdAGENTS.md
- .agents/skills/refresh-kb/AGENTS.mdAGENTS.md
- .agents/skills/riff/AGENTS.mdAGENTS.md
- .agents/skills/save-pdf-kb/AGENTS.mdAGENTS.md
- .agents/skills/save-url-kb/AGENTS.mdAGENTS.md
- .agents/skills/write-phase-plan/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- kb/AGENTS.mdAGENTS.md
- personal-website/AGENTS.mdAGENTS.md
- scripts/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- assumption-auditSkill
- decision-matrixSkill
- direct-setupSkill
- direct-verifySkill
- first-principles-thinkingSkill
- percolate-kbSkill
- percolate-readingSkill
- phase-final-reviewerSkill
- phase-implementerSkill
- phase-orchestratorSkill
- phase-reviewerSkill
- plan-kbSkill
- pr-cleanupSkill
- query-kbSkill
- question-forgeSkill
- refresh-kbSkill
- riffSkill
- save-pdf-kbSkill
- save-url-kbSkill
- write-phase-planSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 10 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Treat size as a discovery signal, never as deletion authority.
- Distinctive: line 26
Stop for a new choice when cleanup would include personal files, application state, credentials, active sessions, database volumes, dirty …
- Distinctive: line 30
Never expand "delete caches" into repositories, application support, or user history.
- Distinctive: line 51
Prefer supported pruning commands over raw deletion when they preserve useful state.
- Distinctive: line 56
Use the bundled script from the repository root:
- Distinctive: line 80
After reviewing the audit and receiving deletion authority, pass every approved path explicitly:
- Very specific: line 108
Never delete Docker.raw directly and never infer that volumes are disposable.
- Very specific: line 110
Editor/Application Support databases: treat as user state even when unusually large.
- Distinctive: line 113
Codex or agent sessions: treat active and archived sessions as user history.
- Distinctive: line 118
If free space is too low for normal tools, reclaim one small, high-confidence reproducible target first.
- Distinctive: line 127
Verify removed worktrees no longer appear in git worktree list.
- Distinctive: line 134
Do not describe a partial cleanup as complete when a command failed or a target was skipped.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Reclaim disk space
Treat size as a discovery signal, never as deletion authority. Prefer a smaller verified cleanup over a broad deletion with ambiguous ownership.
Establish authority
Classify the request before mutating anything:
- For "inspect," "audit," "what can I delete," or equivalent, perform read-only discovery and return a ranked plan.
- For an explicit request to delete a named category, treat that category as approved. Re-resolve its exact targets immediately before deletion.
- Stop for a new choice when cleanup would include personal files, application state, credentials, active sessions, database volumes, dirty Git state, or anything outside the approved category.
Never expand "delete caches" into repositories, application support, or user history. Never expand "delete worktrees" into branches.
Audit in phases
- Record
df -h .. - Inspect likely roots with bounded
ducalls. Usedu -x -d 1 <root>on macOS; remember its default units are 512-byte blocks. Usedu -sk <path>when reporting KiB/GiB. - Drill into only the largest relevant roots. Do not launch overlapping whole-home scans that repeatedly traverse the same files.
- Classify each candidate:
- Reproducible: build output, package caches, model caches, derived data, and clean merged worktrees.
- Conditionally reproducible: simulators, Docker images, offline media, application runtime bundles, and dependency installations.
- User state: documents, Git changes, app databases, chat/session history, credentials, Docker volumes, and editor global state.
- Report exact paths, physical sizes, why each is safe or risky, and the expected recovery. Do not count sparse-file apparent size as physical usage.
Prefer supported pruning commands over raw deletion when they preserve useful state. Close an application before deleting its caches.
Clean Git worktrees
Use the bundled script from the repository root:
bun run .agents/skills/reclaim-disk-space/scripts/worktree-cleanup.tsThe default is audit-only. It fetches the default remote, preferring origin
when present, resolves that remote's symbolic HEAD, and labels every registered
worktree. When the integration branch differs or the remote HEAD is not
available, name an explicit remote-tracking branch:
bun run .agents/skills/reclaim-disk-space/scripts/worktree-cleanup.ts \
--target upstream/trunkA candidate is removable only when all of these hold:
- It is neither the repository's primary worktree nor the worktree invoking the script.
- Its exact path is still registered.
- The directory exists.
git status --porcelainis empty, including untracked files.- Its
HEADis an ancestor of the freshly fetched remote target.
After reviewing the audit and receiving deletion authority, pass every approved path explicitly:
bun run .agents/skills/reclaim-disk-space/scripts/worktree-cleanup.ts \
--target upstream/trunk \
--remove /exact/clean-worktree-one \
--remove /exact/clean-worktree-twoThe script validates the whole manifest before deleting the first path,
revalidates each path at action time, and calls git worktree remove without
--force. It never deletes branches. Do not replace this with rm, a glob, a
prefix sweep, or a broad temporary-directory cleanup.
Exclude dirty, unmerged, missing, unregistered, primary, and current worktrees. Preserve them and name the failed predicate.
Handle common large categories
- Build output and dependency caches: safe when reproducible, but note the reinstall or rebuild cost.
- Xcode DerivedData: reproducible. Keep archives and signing material out of scope.
- Simulator devices: inspect runtimes and device state first. Prefer
xcrun simctl delete unavailable; require explicit approval to delete active devices. - Docker: inspect images, build cache, containers, and volumes separately.
Never delete
Docker.rawdirectly and never infer that volumes are disposable. - Editor/Application Support databases: treat as user state even when
unusually large. A file named
state.vscdb,workspaceStorage, orglobalStoragemay hold history. Do not delete it as a cache. - Codex or agent sessions: treat active and archived sessions as user history. Delete only when the user explicitly accepts that loss.
- Package/model caches: usually redownloadable. State the network and wall-clock cost before removal.
If free space is too low for normal tools, reclaim one small, high-confidence reproducible target first. Do not attempt an in-place database vacuum that needs temporary space larger than the available capacity.
Verify and report
After deletion:
- Run
df -h .again. - Verify removed worktrees no longer appear in
git worktree list. - Report removed targets, refusals, recovered space, and remaining risky candidates.
- State whether recovery is possible: caches are redownloadable; removed worktree branches and commits remain; untracked files would not be recoverable and therefore must have blocked deletion.
Do not describe a partial cleanup as complete when a command failed or a target was skipped.
This workflow is adapted from an MIT-licensed upstream repository skill.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

