CacheFerret

CacheFerret finds rebuildable developer caches across macOS and Linux, shows where the disk space went, and removes the caches you choose. Run it in a terminal for a fast, keyboard-first workspace; pipe it for structured JSON.

Opening the TUI starts with a scan. Focus a cache and press d to delete it; recent, large, shared, unknown-age, and download-backed caches ask first.

Install

# Homebrew on macOS or Linux
brew install rvben/tap/cacheferret

# Cargo
cargo install cacheferret

# PyPI / pipx
pipx install cacheferret

Release archives include checksums, documentation, and completions for Bash, Zsh, Fish, PowerShell, and Elvish on Intel and ARM Linux and macOS.

Quick start

# Open the interactive cache workspace
cacheferret

# Open the workspace for one source tree
cacheferret tui --root ~/Projects --scope project

# Produce plain or structured scan output without opening the TUI
cacheferret scan --root ~/Projects --scope project

# Preview old project caches that are eligible for cleanup
cacheferret clean --root ~/Projects --dry-run

# Clean after an interactive confirmation
cacheferret clean --root ~/Projects

# Confirm from a script or agent
cacheferret clean --root ~/Projects --yes

# Shared caches are never part of the default clean scope
cacheferret clean --scope global --include-recent --dry-run
cacheferret clean --scope global --include-recent --yes

Inside the TUI, use the arrow keys or j/k to move, d to delete the focused cache, / to filter, and Tab to cycle scopes. Risky deletes use a compact y/n prompt. Press ? for the complete shortcut guide. Catalog entries marked scan-only cannot be deleted.

CacheFerret adapts automatically to truecolor, 256-color, basic ANSI, no-color, and non-UTF-8 terminals. Set NO_COLOR=1 for an uncolored interface, CACHEFERRET_ASCII=1 for ASCII-only glyphs, or CACHEFERRET_REDUCE_MOTION=1 for static progress indicators.

Output is human-readable on a terminal and JSON when piped:

cacheferret scan --limit 20 --fields kind,path,bytes |
  jq '.items[] | select(.bytes > 1073741824)'

Safety model

• Bare cacheferret opens the TUI on a terminal and emits a read-only JSON scan when piped. cacheferret scan never mutates the filesystem.
• The TUI uses focused-item deletion: move to a cache and press d. It confirms recent, large, shared, unknown-age, and download-backed caches.
• Pressing d remeasures the focused cache before deciding whether confirmation is required; confirming triggers another identity and ownership check.
• clean defaults to project caches; shared global caches require an explicit --scope global or --scope all.
• The batch clean command protects caches modified in the last seven days unless --include-recent is passed. Change the window with --protect-days.
• A non-interactive clean refuses to run without --yes and exits with the declared confirmation_required error.
• Cache roots must match a closed catalog and their project ownership markers.
• Symlinks are never followed.
• Immediately before each deletion, CacheFerret checks the path, filesystem identity, scan-root containment, kind, and ownership markers again.
• Targets that need package downloads to restore are identified in scan and clean output.
• Shared stores that can contain or back irreplaceable project state are scan-only and remain excluded even with --include-recent --yes.
• --dry-run follows the same discovery and eligibility policy without deleting anything, and lists every selected path with its size and restore requirements.

Reclaimed bytes are an estimate based on the freshly measured directory size; filesystem free-space deltas can differ because of snapshots, compression, hard links, or concurrent writes.

Supported caches

cacheferret catalog returns the complete machine-readable catalog. The first release covers:

Docker build data is intentionally not treated as a directory cache. It needs a separate native docker builder prune integration with Docker-aware sizing and is planned as a follow-up.

The Maven local repository is scan-only because it may contain unpublished locally installed artifacts. The shared renv cache is scan-only because project libraries may link packages from it.

Commands

Use cacheferret <command> --help for every option.

Agent contract

CacheFerret follows clispec.dev v0.3:

• explicit JSON via --output json and automatic JSON when piped;
• data on stdout and diagnostics on stderr;
• structured error envelopes as the last stderr line in JSON mode;
• offline schema introspection with effects, cardinality, pagination, output fields, confirmation gates, and stable exit codes;
• offset pagination and --fields for the unbounded scan result;
• honest read_only and idempotent effect declarations.

cacheferret schema
cacheferret schema clean

Development

make check        # format, clippy, and tests
make conformance  # build and score the CLI against clispec.dev

See docs/releasing.md for the release checklist and SECURITY.md for private vulnerability reporting.

The generated mascot and wordmark in assets/ are initial brand concepts. A future design pass can trace the chosen mark into deterministic SVG assets.

License

MIT