degu 🐭

Safely inspect and reclaim disk quota from caches and build artifacts on shared HPC and GPU clusters — conservative classification and reversible staging by default.

For ML researchers on login nodes, drowning in pip, conda, HuggingFace, and compile caches.

_{Real output, from a synthetic fixture whose allocated bytes match a working ML node. Not a benchmark: five large files are not a real cache's directory and inode load. Tap for a readable copy.}

A smaller scan as text — copy-pasteable, and kept true by a contract test that rebuilds the fixture and re-runs the CLI against this block

$ degu scan
22.0 MiB detected across 3 locations - 6.0 MiB eligible to clean

Eligible to clean - 1 location - 6.0 MiB
Cleaned by default; a preview checks whether sealed staging can move them.
 source  on disk   idle  inodes  path
 pip     6.0 MiB  today       2  ~/.cache/pip

Needs review - 1 location - 12.0 MiB
Excluded by default; preview a path before including it.
 source        on disk   idle  inodes  reason                path
 huggingface  12.0 MiB  today       3  costly to regenerate  ~/.cache/huggingface/hub/models--bert--base

Not managed - 1 location - 4.0 MiB
Reported only; no clean acts on these locations.
 source  on disk   idle  inodes  reason         path
 uv      4.0 MiB  today       2  managed by uv  ~/.cache/uv

Preview the largest Needs review location (no changes): degu clean -dn --review ~/.cache/huggingface/hub/models--bert--base
Run this preview in a terminal to receive a Next command with the same path and filters.
Scan build artifacts under this project, or any parent directory: degu scan .

Why degu

• Reclaims what actually fills your quota. Built-in sources across the ML/HPC stack — pip, conda, HuggingFace, vLLM, Triton, cargo, and more (degu adapters lists them all) — plus build artifacts under any project tree, found in a single read-only pass; two node-runtime diagnostics stay scan-time opt-in.
• Safe by default. Only verified, cheap-to-regenerate findings enter the default plan and are staged for undo.
• Honest accounting. degu quota reads authoritative filesystem usage and limits, kept separate from degu-detected storage.

Why you can trust it to delete

Deleting the wrong files is the core risk, so degu earns every deletion:

• Corroboration, not names. A directory becomes eligible only on structural evidence that it is regenerable — a tool's own cache marker, a build manifest — never because it is named cache, target, or __pycache__. Among locations degu discovers, anything it cannot corroborate is reported, never cleaned; degu is not a whole-disk file finder.
• Three tiers, conservative by default. Eligible to clean is cheap-to-regenerate cache. Needs review is regenerable but costly (model downloads, compile caches) and stays excluded until you preview an exact path. Not managed — your data, tool-coordinated caches, checkpoints — can never enter a plan.
• Fail closed. If any selected location cannot be fully measured or classified, degu refuses the whole plan instead of guessing. Default cleanup is staged for undo; permanent purge is separately disclosed and confirmed.
• Preview matches execution. degu clean -n runs the same sealed-staging admission checks that execution re-verifies: a location the preview still lists as Eligible to clean has already passed them, and anything that sealed staging cannot execute — external hard links, unsupported metadata, inventory ceilings — is disclosed with its reason up front instead of failing later.

How degu compares

	degu	native cleaners (conda clean, pip cache purge, …)	kondo	ncdu / dust
Scope	ML/HPC cache sources + project artifacts, one pass	one tool each	project artifacts	whole-disk usage
Evidence before deleting	structural corroboration	n/a (the owning tool)	name and layout match	none — measures only
Undo	staged trash, degu undo	deletes in place	deletes in place	deletion is manual
Cross-tool view	yes	no	no	sizes only

For datasets, checkpoints, and unknown large files, pair degu with a disk-usage viewer.

Setup at a glance

Operation	Setup	Boundary
scan, quota, clean -n	none	read-only; dry-run creates no degu state
degu-managed clean, undo, trash purge	degu init for self-managed authority, or optional administrator setup	runs without elevation; anchor, WAL, and each source/trash mount domain independently require a certified ext4/XFS/APFS backend
reclaim uv	explicit executable and cache root	irreversible tool-native mutation; no account anchor, degu trash, or undo

Unsupported filesystems never gain sealed authority. See the safety model for compatibility and recovery behavior.

Installation

Install the latest release (static binaries; Linux x86_64/aarch64 and macOS):

installer=$(mktemp "${TMPDIR:-/tmp}/degu-install.XXXXXX") &&
curl -fsSLo "$installer" "https://github.com/FeathBow/degu/releases/latest/download/degu-install.sh" &&
DEGU_VERSION= sh "$installer" &&
rm -f "$installer"

The downloaded installer is an attested release asset that carries its release version and verifies the archive's SHA-256 checksum before installing; the empty DEGU_VERSION keeps a value exported in your environment from overriding that pinned release.

Or through cargo — cargo binstall degu fetches the same release archives without compiling and fails rather than falling back to a third-party or source build, cargo install degu --locked builds from crates.io.

Alternatively, build from source with Git and the current stable Rust toolchain:

git clone https://github.com/FeathBow/degu.git
cd degu
cargo install --path crates/degu --locked --root "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"

Both degu and its short alias, dg, install into ~/.local/bin by default. DEGU_INSTALL_DIR may select another binary destination when the caller already has permission. A source build installs degu at the checked-out commit. Its installer and account-setup contract are documented in the installation guide.

Quick start

Nothing here changes anything until you say so. Start read-only — no setup, no degu state, no elevation:

degu scan            # what exists, and what is safe to clean

Only Eligible to clean enters a default plan. For one Needs review location, the scan prints a shorter degu clean -dn --review PATH preview, and the Next command it gives back keeps that exact selection.

Decide on one screen

When the decision is about one location rather than a rule, degu tui brings the scan, the clean, and a selective purge together: findings and the staging trash on one screen, chosen per location, handed to the same clean and trash purge implementations with their own plans and confirmations.

degu tui

_{One Needs review location chosen; the header totals what a clean would move. Tap the image for a readable copy.}

Four keys carry the whole decision, and ? opens a scrollable field guide to the rest:

Key	What it does
Space	Put the selected location in the plan, or take it out
t	Show the staging trash — what an earlier clean already moved — and come back
p	Preview the clean these choices describe, changing nothing
c	Hand whichever plans were decided to clean and trash purge, which confirm again

The staging trash is where t goes: each entry names the copy it is, so two copies of one origin are told apart, and what it still costs you in quota. Choosing an entry there marks it for permanent deletion, which c then routes to trash purge rather than to clean. Recovery stays a command of its own — degu undo restores the latest clean, and nothing in the review does that for you.

The review also carries an advisory block on the locations degu could not classify, separating what degu measured from what degu concluded, and from what an advisor of your own thinks if you put one there. Nothing runs and nothing is sent unless you do, which is what an untouched install does on a login node.

Clean, and get it back

Cleanup is the first thing that writes degu state, so check the account once before the first clean / undo / trash purge:

degu doctor

ready means continue. missing means initialize the fixed authority for this non-root account:

degu init

init refuses when this account's store carries an activation record, which means an earlier authority was lost rather than never made. An administrator may instead provision the optional system authority. split_authority, recovery_required, unsafe, unsupported, or uncertain requires investigation; init never repairs state, chooses a UID or path, activates an empty store, or clears recovery.

After that the lifecycle is four short commands:

degu clean -n        # preview the exact plan; changes nothing
degu clean           # stage Ready-to-clean findings into undoable trash
degu undo            # restore the latest clean operation
degu trash purge     # or permanently delete what you reviewed

Staged data stays reversible and still counts against quota until it is purged, so a clean frees your attention before it frees your quota. Choose one recovery branch per clean operation. A confirmed mutating clean also permanently purges trash entries at least seven days old — that is the only deletion degu performs without being pointed at it, and degu trash list gives each entry's age to measure against.

Staging and permanent deletion do not have the same limits, so some trees can be staged and restored but never permanently deleted: a directory carrying an extended attribute other than the provenance record macOS writes by itself. degu trash purge and the seven-day expiry retain such an entry — still restorable by degu undo — and go on deleting the rest, so its space stays allocated and waiting does not change that. Hard links pointing at each other inside the tree are deleted like anything else, one name at a time; what they do not promise is the amount of space returned, because a name outside the tree keeps the data alive. degu clean -n says which limit applies before anything moves, as purge_admission in --json; the safety model has the whole rule.

Large shared filesystems

A full first scan can take minutes:

degu scan --budget 300s

A time budget returns honest lower bounds: truncated sections are flagged, totals are marked as lower bounds, and the report says how many directories went unvisited. The user guide and safety model cover recovery and permanent deletion in detail.

Include project builds

Pass a project root when you also want build artifacts below it. The root can be a single project or a parent directory holding many projects. Scope is not remembered between commands, so pass the same root again to authorize its cleanup preview:

degu scan .
degu clean . --dry-run

To include a project tree in every degu scan, add it to roots in the configuration. Configured roots are for reading: clean and tui both require the root as an explicit argument before anything under it can enter a plan.

Check filesystem quota

degu quota

Validated on Linux ext4 and field-validated on a Lustre 2.15 client; other filesystems and macOS report unsupported instead of guessing. See the user guide for supported providers and failure behavior.

Run degu <command> --help or degu man <command> for complete command details.

Documentation

• Installation covers tagged installers, release archives, and release verification.
• User guide covers project scans, exact-path review, JSON automation, recovery, and cache relocation.
• Configuration documents every supported setting and adapter selection.
• Operational safety defines cleanup authority, staging, permanent deletion, and filesystem boundaries.

License

degu is available under your choice of the Apache License 2.0 or the MIT License. Contributions are dual licensed under the same terms.