Disk Cleanup
Deterministic by design. All target knowledge lives in targets.json; all measuring and
deleting lives in scripts/survey.py (read-only) and scripts/clean.py (executor, dry-run by
default). They run headless with zero dependencies (stdlib only) — a user can run them in a
terminal without any agent. The agent's job is small: run the scripts, relay the compressed
output, and decide the handful of things that need human judgment.
The two scripts
python3 scripts/survey.py # read-only: sizes, risk, flags, uncategorized. Touches nothing.
python3 scripts/survey.py --json # same, machine-readable (preferred for the agent)
python3 scripts/clean.py --preset safe # DRY-RUN plan (default — nothing deleted)
python3 scripts/clean.py --preset safe --go # execute (safe risk only)
python3 scripts/clean.py --preset full --allow-medium --go --empty-trash # safe+medium, then empty Trash
python3 scripts/clean.py --ids cargo-registry-cache,go-mod-cache --go # specific targets
python3 scripts/clean.py --preset safe --skip ollama-models --go # exclude one
trash is used for all file removal (never rm); freed space sits in Trash until emptied
(--empty-trash, or the user empties it). Sizes are du estimates — approximate on APFS.
Safety model (enforced in code, not prose)
- Risk gating:
safe runs automatically; medium needs --allow-medium; never is
refused even if named by id. advisory targets only print guidance, never execute.
- Preflight on every trashed path: canonical
realpath → must resolve under an
allowed_roots entry → must not be a symlink → never $HOME or /. Anything failing is
skipped and reported, not deleted.
- Dry-run by default:
clean.py prints the plan and touches nothing unless --go.
Agent workflow
- Run
python3 scripts/survey.py --json. Relay the compressed summary: disk free,
safe/medium recoverable totals, any flags (e.g. crash-loop), and the top targets.
Do not dump the whole JSON.
- Auto-path: for a plain "clean up safe stuff", show the
safe total and run
clean.py --preset safe --go (offer --empty-trash). Safe targets are regenerable.
Disk-full emergency (ENOSPC is blocking other work): don't start with the full safe
preset. It quits running apps (electron-app-caches: Notion, Figma, Obsidian, Codex,
Dropbox), and its trash-method targets free nothing until the Trash is emptied, which also
deletes the user's other trashed items. Run the command-method caches first, because they free
space immediately: clean.py --ids uv-cache,npm-cache --go. Command-method caches often free
far more than their du estimate.
- Escalate to the user ONLY for (these are genuine judgment calls the scripts deliberately
refuse to auto-decide):
medium targets (ML models, device support, project node_modules) — confirm before --allow-medium.
ML-model targets (ollama-models, huggingface-models) carry a last_used_days field
(newest file atime under the target, aggregate across all models in that store — not
per-model) as a "how stale is this" signal; surface it before suggesting deletion.
uncategorized discoveries — unknown dirs >100 MB; ask or investigate before adding.
advisory notes — surface them (Telegram cache, simulators via simctl, uv/tools,
Chrome whole-dir, Xcode Archives, mo clean deep-clean); never act on them automatically.
For mole-deep-clean: suggest the user run mo clean themselves (interactive TUI, permanent
deletes, sudo for system caches) — never invoke it from the agent. Never shell out to mo
at all (not even --dry-run): it's TUI-only and blocks waiting for a real terminal even in
dry-run mode — confirmed hanging under a piped subprocess, stdin=DEVNULL, and even a
script(1)-allocated pty. A mole flag in survey.py's output only reads the mtime of
mole's own leftover ~/.config/mole/clean-list.txt (last-run recency), never invokes it.
- surgical Docker / simulator decisions (see below).
- Run
clean.py with the resolved selection. Relay the result (freed_human, disk before→after).
Maintaining the registry
Add or correct targets by editing targets.json — no code change needed. Each target:
{id, category, risk, method, paths|find, regenerates, priority, note}. Methods:
trash — trash literal paths (globs allowed).
find-trash — exact-name dir sweep with a min_mb floor (crash dumps, project node_modules).
command — run a CLI (npm cache clean…); set scope_path so freed bytes can be measured.
simctl — xcrun simctl delete unavailable (removes only sims for uninstalled runtimes; safe).
downloads-scan — config-driven (config.json → downloads_scan): files older than age_days
whose name doesn't match exclude_patterns. The dry-run lists every file by name for review.
advisory — never executes; only prints guidance.
Keep installed software at risk: never (learned the hard way: uv/tools, uv/python,
~/.rustup/toolchains, ~/.bun, ~/.deno are NOT caches). Every non-advisory target's paths
must resolve under allowed_roots or preflight will (correctly) refuse them.
Customization & setup (per-machine, never committed)
config.json ships generic, public-safe defaults. Anything personal — names, family
names, a non-English tax/legal/financial vocabulary — or machine-specific goes in
config.local.json (gitignored). load_config() deep-merges it over config.json:
lists are unioned (local terms only add protection to the Downloads exclude list), scalars
override. See config.local.example.json for the shape.
Setup mode — when the user first uses the skill, asks to personalize it, or has sensitive
files in ~/Downloads, offer to build config.local.json by asking (one short batch):
- Names/keywords in Downloads filenames that must never be swept (own name, family names).
- Their language's tax/legal/financial terms (e.g. German
steuer, rechnung, vertrag).
- Their projects directory (for the
node_modules sweep) and any extra app caches.
Then write config.local.json (copy config.local.example.json and fill it in). Confirm what
was saved. Never commit it.
Projects directories live in projects_roots (config.json defaults to ~/Projects; set your
own in config.local.json). They are added to allowed_roots at load time and swept by the
node-modules-projects target, whose find root is @projects. Targets whose paths don't exist
on this machine simply measure 0 and are skipped.
Still agent-driven (only what genuinely can't be deterministic)
- Docker only — surgical and stateful: survey with
docker images / docker ps -as /
docker system df -v, let the user pick per-name (docker rm/rmi/volume rm/builder prune),
or blunt docker system prune -a -f. A named volume removed = data gone; confirm by name.
(Everything else — simulators via the simctl method, Downloads via downloads-scan,
crash dumps, all caches — now runs through the scripts.)
1---2name: disk-cleanup3description: 'Scan and clean macOS caches, package-manager data, crash dumps, and app caches to reclaim disk space. Deterministic — a config registry (targets.json) plus two scripts (survey.py read-only, clean.py executor) do all the measuring and deleting; the agent only relays a compressed summary and makes the few human-judgment calls. IMPORTANT — use this skill whenever the user''s request on macOS involves: freeing disk space, cleaning/clearing caches, "disk is full", "clean up my Mac", "free up space", "what''s eating my disk", "running low on disk", needing space for an install, or any low-storage complaint. Covers the whole workflow survey → choose → clean → empty Trash.'4metadata:5 source: https://skillmd.com/skills/glebis/disk-cleanup6---78# Disk Cleanup910**Deterministic by design.** All target knowledge lives in `targets.json`; all measuring and11deleting lives in `scripts/survey.py` (read-only) and `scripts/clean.py` (executor, **dry-run by12default**). They run headless with **zero dependencies** (stdlib only) — a user can run them in a13terminal without any agent. The agent's job is small: run the scripts, relay the compressed14output, and decide the handful of things that need human judgment.1516## The two scripts1718```bash19python3 scripts/survey.py # read-only: sizes, risk, flags, uncategorized. Touches nothing.20python3 scripts/survey.py --json # same, machine-readable (preferred for the agent)2122python3 scripts/clean.py --preset safe # DRY-RUN plan (default — nothing deleted)23python3 scripts/clean.py --preset safe --go # execute (safe risk only)24python3 scripts/clean.py --preset full --allow-medium --go --empty-trash # safe+medium, then empty Trash25python3 scripts/clean.py --ids cargo-registry-cache,go-mod-cache --go # specific targets26python3 scripts/clean.py --preset safe --skip ollama-models --go # exclude one27```2829`trash` is used for all file removal (never `rm`); freed space sits in Trash until emptied30(`--empty-trash`, or the user empties it). Sizes are `du` estimates — approximate on APFS.3132## Safety model (enforced in code, not prose)3334- **Risk gating:** `safe` runs automatically; `medium` needs `--allow-medium`; `never` is35 refused even if named by id. `advisory` targets only print guidance, never execute.36- **Preflight on every trashed path:** canonical `realpath` → must resolve under an37 `allowed_roots` entry → must not be a symlink → never `$HOME` or `/`. Anything failing is38 skipped and reported, not deleted.39- **Dry-run by default:** `clean.py` prints the plan and touches nothing unless `--go`.4041## Agent workflow42431. Run `python3 scripts/survey.py --json`. Relay the **compressed** summary: disk free,44 `safe`/`medium` recoverable totals, any `flags` (e.g. crash-loop), and the top targets.45 Do not dump the whole JSON.462. **Auto-path:** for a plain "clean up safe stuff", show the `safe` total and run47 `clean.py --preset safe --go` (offer `--empty-trash`). Safe targets are regenerable.48 **Disk-full emergency** (ENOSPC is blocking other work): don't start with the full `safe`49 preset. It quits running apps (`electron-app-caches`: Notion, Figma, Obsidian, Codex,50 Dropbox), and its `trash`-method targets free nothing until the Trash is emptied, which also51 deletes the user's other trashed items. Run the command-method caches first, because they free52 space immediately: `clean.py --ids uv-cache,npm-cache --go`. Command-method caches often free53 far more than their `du` estimate.543. **Escalate to the user ONLY for** (these are genuine judgment calls the scripts deliberately55 refuse to auto-decide):56 - `medium` targets (ML models, device support, project `node_modules`) — confirm before `--allow-medium`.57 ML-model targets (`ollama-models`, `huggingface-models`) carry a `last_used_days` field58 (newest file atime under the target, aggregate across all models in that store — not59 per-model) as a "how stale is this" signal; surface it before suggesting deletion.60 - `uncategorized` discoveries — unknown dirs >100 MB; ask or investigate before adding.61 - `advisory` notes — surface them (Telegram cache, simulators via `simctl`, `uv/tools`,62 Chrome whole-dir, Xcode Archives, `mo clean` deep-clean); never act on them automatically.63 For `mole-deep-clean`: suggest the user run `mo clean` themselves (interactive TUI, permanent64 deletes, sudo for system caches) — never invoke it from the agent. **Never shell out to `mo`65 at all** (not even `--dry-run`): it's TUI-only and blocks waiting for a real terminal even in66 dry-run mode — confirmed hanging under a piped subprocess, `stdin=DEVNULL`, and even a67 `script(1)`-allocated pty. A `mole` flag in survey.py's output only reads the mtime of68 mole's own leftover `~/.config/mole/clean-list.txt` (last-run recency), never invokes it.69 - surgical Docker / simulator decisions (see below).704. Run `clean.py` with the resolved selection. Relay the result (`freed_human`, disk before→after).7172## Maintaining the registry7374Add or correct targets by editing `targets.json` — no code change needed. Each target:75`{id, category, risk, method, paths|find, regenerates, priority, note}`. Methods:76- `trash` — trash literal paths (globs allowed).77- `find-trash` — exact-name dir sweep with a `min_mb` floor (crash dumps, project `node_modules`).78- `command` — run a CLI (`npm cache clean`…); set `scope_path` so freed bytes can be measured.79- `simctl` — `xcrun simctl delete unavailable` (removes only sims for uninstalled runtimes; safe).80- `downloads-scan` — config-driven (`config.json` → `downloads_scan`): files older than `age_days`81 whose name doesn't match `exclude_patterns`. The dry-run **lists every file by name** for review.82- `advisory` — never executes; only prints guidance.8384Keep installed software at `risk: never` (learned the hard way: `uv/tools`, `uv/python`,85`~/.rustup/toolchains`, `~/.bun`, `~/.deno` are NOT caches). Every non-advisory target's paths86must resolve under `allowed_roots` or preflight will (correctly) refuse them.8788## Customization & setup (per-machine, never committed)8990`config.json` ships **generic, public-safe defaults**. Anything personal — names, family91names, a non-English tax/legal/financial vocabulary — or machine-specific goes in92**`config.local.json`** (gitignored). `load_config()` deep-merges it over `config.json`:93**lists are unioned** (local terms only *add* protection to the Downloads exclude list), scalars94override. See `config.local.example.json` for the shape.9596**Setup mode** — when the user first uses the skill, asks to personalize it, or has sensitive97files in `~/Downloads`, offer to build `config.local.json` by asking (one short batch):981. Names/keywords in Downloads filenames that must **never** be swept (own name, family names).992. Their language's tax/legal/financial terms (e.g. German `steuer`, `rechnung`, `vertrag`).1003. Their projects directory (for the `node_modules` sweep) and any extra app caches.101Then write `config.local.json` (copy `config.local.example.json` and fill it in). Confirm what102was saved. Never commit it.103104Projects directories live in `projects_roots` (`config.json` defaults to `~/Projects`; set your105own in `config.local.json`). They are added to `allowed_roots` at load time and swept by the106`node-modules-projects` target, whose find root is `@projects`. Targets whose paths don't exist107on this machine simply measure 0 and are skipped.108109## Still agent-driven (only what genuinely can't be deterministic)110111- **Docker only** — surgical and stateful: survey with `docker images` / `docker ps -as` /112 `docker system df -v`, let the user pick per-name (`docker rm`/`rmi`/`volume rm`/`builder prune`),113 or blunt `docker system prune -a -f`. A named volume removed = data gone; confirm by name.114 (Everything else — simulators via the `simctl` method, Downloads via `downloads-scan`,115 crash dumps, all caches — now runs through the scripts.)