mcpField
F
free-disk-space

free-disk-space

github.com/bholmesdevProductivity17994 installsUpdated 1w ago
Repository

About free-disk-space

A macOS skill for auditing disk usage and reclaiming space while protecting user data. It prioritizes regenerable build artifacts and caches, and asks before removing other content or app data.

Key features

  1. 01Check available disk space
  2. 02Survey selected large directories
  3. 03Clean build artifacts and tool caches
  4. 04Review git worktrees before removal
  5. 05Offload files to an external drive

Use cases

  1. 01Recover space from build outputs
  2. 02Prune package-manager and language caches
  3. 03Find stale merged worktrees
  4. 04Move large files to external storage

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/bholmesdev/skills --skill free-disk-space

After installing, type/free-disk-spacein Claude Code to confirm it loaded.

Details

From the project README

Free Disk Space (macOS)

Audit the disk, clear what's safely regenerable, and confirm before touching anything that isn't.

Ground rules

  • Use trash (if the CLI is available) instead of rm -rf. Accumulate in Trash; ask the user to empty it once at the end.
  • Prefer a tool's own cleanup command over deleting its directories (go clean -cache, brew cleanup --prune=all, pnpm store prune, npm cache clean --force, cargo clean).
  • Measure with df -h /System/Volumes/Data (not plain df /).
  • Do not clear GUI app data. ~/Library/Caches/<App> and ~/Library/Application Support/<App> often hold logins, cookies, and history. Leave them alone unless the user names a specific app and accepts the risk. Prefer build cleanup, package-manager prune, stale worktrees, and external-drive offload instead.

Workflow

1. Assess

df -h /System/Volumes/Data; ls /Volumes. Note free space and whether an external drive is mounted.

2. Survey

Targeted du -sh ... | sort -hr — not a full scan of ~. Usual big ones:

  • Build artifacts: target/ (every worktree too), node_modules/, Xcode DerivedData
  • Package-manager caches: go-build, Homebrew, pnpm/npm/pip stores — clean via CLI
  • Large media: CapCut, Screen Studio, Movies, Downloads
  • Report app caches / Application Support sizes only; don't auto-delete them
3. Clear safe tier without asking

Build artifacts and package-manager / language-tool caches only. Everything else (app data, media, model weights, toolchains): summarize sizes and ask, or propose offload.

4. Audit git worktrees

For each worktree: dirty? unique/unpushed commits? Clean + fully merged/pushed → git worktree remove and git branch -d (never -D). Keep and report anything dirty or ahead.

5. Offload keepers

rsync -a → verify sizes → trash original → symlink old path. Symlink individual folders, not whole special dirs like ~/Movies. Warn the app needs the drive mounted.

6. Wrap up

What freed immediately, what's in Trash, what you left alone. Ask user to empty Trash and re-check df.

Comments

Markdown supported