Adonis0123/adonis-skills / skills/disk-tidy
disk-tidy
VerifiedFree disk space on a developer's Mac (Linux partly) when the disk is nearly full: measure where the space went across build output, package-manager caches, app data, AI agent data, old tool versions and worktrees, fan the read-only survey out to subagents, merge it into a tiered cleanup list, clean only what the user approves, and report the real gain from free space before and after. Use whenever the user says the disk or SSD is (almost) full, asks what is eating space, what can be cleaned or deleted to free space, or why free space keeps shrinking, in any language, Chinese included. Hands organizing personal files to file-tidy and removing git worktrees to worktree-tidy. Not for organizing files without a space problem, a single known cache command, system files that need sudo, iCloud or other cloud storage plans, or disks of remote servers, containers and Kubernetes nodes.
Disk Tidy
Find out where a nearly full disk went, then free space without losing anything the owner still needs. You measure and propose; the user decides per item; you clean and prove the gain.
TIDY=<this skill's directory>/scripts/disk_tidy.py (Python 3.9+, standard library only) does the parts that must be exact: free space, well-known locations, and build output that is safe to delete. Use absolute paths.
Ground rules
Each rule protects something that is hard to get back.
- Survey read-only. Nothing is deleted, moved or emptied before the user picks it from the cleanup list. A cleanup the user approved stays within what they picked.
- Never empty the Trash, and say so. Apps and user files go to the Trash so the owner can put them back; the space returns only when the owner empties it.
- Never open credential, token, cookie or chat content. Judge app data, profiles and session folders by name, size and date. If a config points at a key file (for example
GOOGLE_APPLICATION_CREDENTIALS), report the path, never the contents, and leave the file where it is. - Check what is in use right before deleting: process working directories (
lsof -d cwd), the binary each running session executes, and dev servers. Keep any version a running process uses, the version a launcher links to, and the one before it. - Delete build output only when git ignores it (
git check-ignore). A folder that merely looks like a cache but is tracked or outside git is real work until shown otherwise. - Prefer each tool's own cleaner (
uv cache prune,pnpm store prune,npm cache clean --force,brew cleanup, in-app storage managers) overrm, because it knows what is still referenced. duoverstates what deletion frees: APFS clones (pnpm, uv and Next.js copy files that way) and hard links are counted once per path. Quotedusizes as estimates and report only thefreedifference as the result.
Workflow
1. Snapshot
Run python3 "$TIDY" free --note before-cleanup. Every call is appended to ~/.local/state/disk-tidy/free.jsonl and compared with the previous snapshot, so "it shrank again since last time" gets a measured answer; when there is no earlier snapshot, say the weekly change cannot be computed. Start du -xhd1 ~ | sort -hr | head -30 in the background: it can take many minutes on a large home and tells you which top-level folders to look into.
macOS has no timeout command. Bound every slow du, including each one inside a loop, so one huge folder cannot stall the survey:
ls -d ~/code/*/ | while read -r dir; do
perl -e 'alarm shift; exec @ARGV' 120 du -sk "$dir" || echo "timeout $dir"
done
Find the code roots instead of assuming them: the user's words first, then folders holding several git repositories (find ~ -maxdepth 3 -name .git -prune -not -path '*/Library/*' 2>/dev/null, grouped by parent). Ask when it is unclear which roots to scan.
2. Survey in slices
Split the survey by owner so slices don't overlap. With subagents available, run the slices in parallel, each read-only and each told to return a table of path, size, what it is, tier, how to clean, and risk, listing only items above about 500 MB. Without subagents, do the slices in turn.
| Slice | Covers | Start with |
|---|---|---|
| Build output and dev caches | .next, .turbo, node_modules/.cache (webpack, babel, Remotion), Cargo target and similar under the code folders; package-manager caches; toolchains; Docker | python3 "$TIDY" artifacts <code roots> --out <scratch>/artifacts.json, python3 "$TIDY" known |
| Apps and system | ~/Library/Application Support, Containers, Group Containers, Caches, /Applications with last-used dates (mdls -name kMDItemLastUsedDate), iOS backups, local snapshots (tmutil listlocalsnapshots /) | known rows of tier B |
| AI agent data and repositories | each agent home (~/.claude*, ~/.codex*, ~/.grok*, ~/.cursor, ...): sessions by month, upgrade leftovers, old CLI versions; repository and worktree sizes, last commit, unpushed work | ls -la first: shared folders are often symlinks and must not be counted twice |
| The owner's files | Downloads, Desktop, Documents, Movies, large files, duplicates, installers | the file-tidy skill, if installed: its scan and dupes are read-only |
references/hotspots.md lists where space usually hides on a developer machine and how each place is cleaned; read it before writing the slice prompts.
3. Look for growth that will come back
A pile of near-identical items with consecutive dates means something keeps recreating them. Clearing it without stopping the cause only buys time. Examples: dozens of copies of one package in the uv cache (an MCP server launched with uvx or uv tool run and no pinned version), hundreds of marketplace-upgrade-* folders, a .next/dev that grows with every dev session. Find the source (agent MCP configs, launch agents, the tool's settings) and report it with the cleanup item. Say plainly when the source is gone and the pile is only history.
4. Merge into one list
Merge the slices, drop paths two slices both counted, and sort by size into tiers:
- A, rebuildable: caches and build output that tools recreate on demand; old tool versions nothing runs.
- B, owner decides: data with value or side effects: chat media, sessions, Docker images, rendered videos, app profiles, unused apps, worktrees, repositories not touched for months.
- C, keep: in use, irreplaceable, or owned by the system.
Show A and B as tables with size, what is lost, and the risk, with an A total that is honest about clones. Ask which groups to clean; the host's question tool with multi-select works well here.
5. Clean what was picked
- Build output:
python3 "$TIDY" clean <artifacts.json>as a dry run, then--yes. It deletes only known build-output folder names that git ignores and that no dev or build process uses (editors, shells and agents sitting in a repository root do not count; any process inside the folder itself does), re-checks each just before deletion, and prints the free-space gain. - Caches: the tool's own cleaner from the hotspots list.
- Old versions and leftovers: list exact targets with sizes, check running binaries (
lsof -p <pid>for each session) and launcher links, keep current and previous, then delete. Re-run each tool's--versionafterwards. - Worktrees: the worktree-tidy skill. Removing worktrees frees less than
dusuggests becausenode_modulesis cloned. - Apps: quit check with
pgrep, then move the.appand its own Library folders (Application Support, Containers, Group Containers, Caches, Preferences, Saved Application State, matched by bundle id) to the Trash through Finder:osascript -e 'tell application "Finder" to delete {POSIX file "<path>", ...}'. Finder may answer-15260(busy); wait a few seconds and retry. Confirm each path is gone. - In-app data (WeChat, Feishu, WeCom, Chrome site storage): tell the user where the app's storage manager is; do not delete these folders behind the app's back.
- The owner's files: the file-tidy skill, with its Plan and dry run.
A step that fails stops that group; report it instead of working around it.
6. Report
- free space before and after (
free --note after-cleanup), and the gain per group where it was measured - what is in the Trash and its size, and that it frees space only once emptied
- anything that will grow back and its cause
- what stayed (B items not picked, blocked items and why) and the next candidates
- anything not verified, such as sizes
ducould not read without sudo
Boundaries
- Organizing files without a space problem belongs to file-tidy; this skill only hands it the owner's-files slice.
- System folders that need sudo, Time Machine, and APFS snapshots are reported, not touched.
- On Linux the build-output, cache and agent slices apply as written; app data lives in
~/.config,~/.local/shareand~/.cacheinstead of~/Library. Windows is not covered.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |