agentleFS
tyler-berggrentyler-berggren/tb-claude-kit/.claude/skills/disk/SKILL.md

disk

Skill2 starsChanged 5 days agoMITView on GitHub

See where this Mac's disk space went across every drive, internal and external, and win it back. Says what created each big item, then clears it, redirects the tool that makes it, moves it to another drive, or archives a dormant project whose remote is current, only what the user picks. `/disk setup` maps the drives once; `/disk report` changes nothing.

  • Reads credentials
  • Deletes or force-pushes

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. tony/skills★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository24 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 2 are distinctive, and 12 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 12

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Ask its role. Recommend warm for the first one.

    line 79
  2. Very specific:

    Ask whether it is always attached.

    line 81
  3. Distinctive:

    Ask its floor. Recommend 5% of its size, rounded to 5 GB.

    line 83
  4. Very specific:

    If a WorktreeCreate hook is already there and isn't the kit's, don't replace it.

    line 118
  5. Distinctive:

    After the report, ask in one round which numbered recommendations to carry out.

    line 162
  6. Very specific:

    Check that the app that owns the item isn't running (pgrep -x "Slack", pgrep -f "Visual Studio Code").

    line 167
  7. Very specific:

    Use the item's own command where there is one (npm cache clean --force, brew cleanup).

    line 169
  8. Very specific:

    Run the how line, with {warm} already filled in by the report.

    line 174
  9. Very specific:

    Run the item's check in a fresh shell (zsh -lc '<check>') and show that it prints the new path.

    line 180
  10. Very specific:

    Run it with --dry-run first and show the line it prints.

    line 186
  11. Very specific:

    Never use it for anything the item's cost warns against.

    line 187
  12. Very specific:

    When the picks are done, run disk report again and show free space before and after for each drive.

    line 197
  13. Very specific:

    An unmounted drive is skipped, and the report says so: Never create a folder under /Volumes/.

    line 203
  14. Very specific:

    If .claude/kit.json has a rules."disk" entry, read it and apply it as an additional instruction for this skill.

    line 211

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Disk

A small internal drive fills up from things nobody chose to keep: caches, build output, leftover agent worktrees, a project untouched since spring. Most of it either comes back on its own or has a better home on another drive. This skill works across the whole machine and every drive attached to it, and it never deletes or moves anything the user didn't pick.

ArgumentWhat happens
setupMap this machine's drives: which is for what, how much free space each must keep. Run once, and again when a drive is added.
(none)Report, then offer the recommended actions and carry out the ones the user picks. Runs setup first when there is no config.
reportMeasure and recommend only. Changes nothing.

The machine config

Drive layout belongs to the machine, not to a project, so it lives outside every repository: ~/.config/claude-kit/disk.json (or $CLAUDE_KIT_DISK_CONFIG). ~/.claude-kit/scripts/disk reads and writes it. Edit it through that script, not by hand.

{
  "drives": [
    { "uuid": "58CF…", "label": "Macintosh HD", "role": "hot",  "floorGB": 40, "alwaysAttached": true },
    { "uuid": "65EF…", "label": "External",     "role": "warm", "floorGB": 50, "alwaysAttached": true }
  ],
  "projectRoots": ["~/dev"],
  "warmAfterDays": 60,
  "coldAfterDays": 365,
  "archiveDir": null,
  "worktreeDir": null,
  "knownItems": []
}
  • Drives are keyed by volume UUID. Names change and collide; the UUID doesn't.
  • role:
    • hot is for active work. It is usually the internal drive.
    • warm takes dormant projects, caches and tool data moved off a hot drive.
    • archive holds archives of projects dropped from disk. A machine with one external drive gives it warm. It then holds archives too.
  • floorGB: the free space this drive must keep. The session-start hook warns below it.
  • alwaysAttached: true for a drive that never leaves the machine (a desktop's dock or a second internal disk). Only an always-attached drive takes tool data, caches or worktrees, because anything pointed at a missing drive breaks. For a drive that comes and goes (a laptop's USB disk), recently touched projects stay on the internal drive.
  • projectRoots: where git projects live, on any drive. /clear-cache reads it too.
  • warmAfterDays / coldAfterDays: a project untouched this long is a candidate to move to a warm drive / to drop from disk (remote only, after its archive).
  • archiveDir: where dropped projects' archives go. Default: disk-archive/ on the first archive drive, else on the first warm drive.
  • worktreeDir: where git worktrees go. Default: worktrees/ on the first always-attached warm drive.
  • knownItems: this user's additions to the skill's knowledge file (see Known items).

The shell is zsh. It aborts on a glob that matches nothing and doesn't word-split variables. Every block below runs under bash for that reason.

Setup

  1. List the drives and any existing config:
    ~/.claude-kit/scripts/disk drives
    ~/.claude-kit/scripts/disk config
    drives lists the internal data volume and every browsable, writable volume under /Volumes. Network shares and disk images are left out.
  2. Interview the user in one round with the question tool: one question per drive. When a config exists, recommend the values it already holds.
    • The internal drive is hot, and always attached. Ask only for its floor. Recommend 15% of its size, rounded to 5 GB, and at least 20 GB.
    • Each external drive:
      • Ask its role. Recommend warm for the first one; for a second one, archive when it is slower or larger, else warm.
      • Ask whether it is always attached. A Mac mini, Studio or iMac suggests yes; a laptop suggests no. Run sysctl -n hw.model to see which.
      • Ask its floor. Recommend 5% of its size, rounded to 5 GB.
    • Where projects live. Suggest ~/dev, plus any folder on an external drive that holds git repositories. Find those with find /Volumes/<name> -maxdepth 3 -name .git -prune 2>/dev/null | head.
  3. Write the answers:
    ~/.claude-kit/scripts/disk set-drive <uuid> --role hot --floor 40 --attached yes
    ~/.claude-kit/scripts/disk set-drive <uuid> --role warm --floor 50 --attached yes
    ~/.claude-kit/scripts/disk set projectRoots '["~/dev", "/Volumes/External/dev"]'
  4. Worktrees off the internal drive. Skip this step unless a warm drive is always attached. Each git worktree Claude Code makes (--worktree, EnterWorktree, subagents with worktree isolation) is a full checkout, often with its own node_modules. They pile up inside the repo. Claude Code has no setting that moves them, and it refuses a symlinked .claude/worktrees, so moving them takes a WorktreeCreate/WorktreeRemove hook pair.
    • Offer to register the pair in ~/.claude/settings.json:
      • wt-create puts each worktree at <worktreeDir>/<repo>-<hash>/<name>. It copies .worktreeinclude files such as .env, and falls back to the repo when the drive isn't mounted.
      • wt-remove keeps a worktree that has uncommitted changes, and keeps a branch that isn't merged.
    • On yes, register them, then check the result with jq '.hooks' ~/.claude/settings.json:
    bash <<'SH'
    f=~/.claude/settings.json; [ -f "$f" ] || echo '{}' > "$f"
    cp "$f" "$f.bak-disk-$(date +%Y%m%d%H%M%S)"
    tmp=$(mktemp)
    jq --arg c "$HOME/.claude-kit/scripts/wt-create" --arg r "$HOME/.claude-kit/scripts/wt-remove" \
      '.hooks = ((.hooks // {}) + {WorktreeCreate: [{hooks: [{type: "command", command: $c}]}],
                                   WorktreeRemove: [{hooks: [{type: "command", command: $r}]}]})' \
      "$f" > "$tmp" && jq empty "$tmp" && mv "$tmp" "$f"
    SH
    If a WorktreeCreate hook is already there and isn't the kit's, don't replace it. Say so and leave it.
  5. Show ~/.claude-kit/scripts/disk status as a short table: each drive's role, free space and floor. Then say what the setup turned on: the session-start warning below each floor, and the worktree hooks when registered.

Report

~/.claude-kit/scripts/disk report          # readable; --json for the full data

It measures every drive and changes nothing. It takes a few minutes on a full disk, so run it in the background and say so. It reports:

  • Each drive: free space against its floor.
  • Known items: known-items.json in this skill's folder, plus the user's knownItems in disk.json, where a user entry replaces one with the same id. Each item shows its size per drive, what creates it, whether it comes back on its own, and the best action. An item whose folder is already a symlink to another drive shows under Already moved off.
  • Unknown big folders: anything of 1 GB or more directly under ~/Library/Caches, Application Support, Containers, Group Containers, ~/.cache or ~/Library/Developer that no known item claims. Name the app from the folder or bundle id, look inside (du -d 3 -h <path> | sort -rh | head) to see what it holds, and suggest an entry for the user's knownItems.
  • Worktrees in every repo under projectRoots, through worktree-sweep. Names matching worktreeKeep (default slot-*, pool-*: pools a project's own tooling reuses) are never removed.
  • Recommendations, grouped by drive. The drive under the most pressure comes first: the internal drive, then the least free space. Within a drive, largest first.

The report is cached in ~/.cache/claude-kit/disk-report.json. The session-start warning names its biggest item for 7 days.

Present it in this order:

  1. One line per drive.
  2. The numbered recommendations, each with size, action and cost.
  3. "Yours to judge": reported, never acted on.
  4. Unknown folders, each with what it most likely is.
  5. Worktrees.

Act (no argument)

After the report, ask in one round which numbered recommendations to carry out. Recommend the ones on drives below their floor, plus anything that regenerates and costs nothing. Then, for each pick:

  • Delete:
    • Check that the app that owns the item isn't running (pgrep -x "Slack", pgrep -f "Visual Studio Code"). If it is, ask the user to quit it, or skip the item.
    • Use the item's own command where there is one (npm cache clean --force, brew cleanup). Otherwise use rm -rf on exactly the measured path.
    • npx: first check ListAgents for other Claude sessions, since their MCP servers run from that folder.
  • Redirect:
    • Run the how line, with {warm} already filled in by the report.
    • An env var always goes through ~/.claude-kit/scripts/disk env VAR VALUE, never by editing ~/.zshenv by hand. It keeps one marked block, replaces a variable already set there, and leaves the user's own lines alone. Remove one with disk env --unset VAR.
    • Then deal with the old folder. When the item regenerates, delete it. Otherwise move it with disk move <old> --to <new parent>, but only once the tool is quit.
    • Run the item's check in a fresh shell (zsh -lc '<check>') and show that it prints the new path.
  • Move (no redirect exists): ~/.claude-kit/scripts/disk move <path>.
    • It copies to <warm>/moved/<path under ~>, checks file count and bytes, then puts a symlink in the folder's place.
    • It refuses when any process has files open there, and when the destination isn't empty.
    • Run it with --dry-run first and show the line it prints.
    • Never use it for anything the item's cost warns against.
  • App data ("yours to judge", such as Chrome profiles or the Claude desktop app's data): never offered. Move it only when the user asks for that folder by name:
    1. Quit the app.
    2. Run disk move.
    3. Warn that an app update can replace the symlink with a fresh empty folder. If it does, the next report shows the folder back on the internal drive.
  • Worktrees: ~/.claude-kit/scripts/worktree-sweep --apply <repos>. Offer --apply-ask only when the user picks the "finished agent still locked by a live session" ones.

When the picks are done, run disk report again and show free space before and after for each drive.

Rules

  • Nothing is deleted or moved without the user picking it. report changes nothing.
  • Never sudo.
  • An unmounted drive is skipped, and the report says so. Never create a folder under /Volumes/. It would land on the internal drive, at the path where the missing drive should be mounted.
  • Never write the config, a cache or a report inside a repository.

Project overrides

If .claude/kit.json has a rules."disk" entry, read it and apply it as an additional instruction for this skill. Absent file or key means no overrides — that is the normal case.

jq -r '.rules."disk" // empty' .claude/kit.json 2>/dev/null

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.