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. Press Space to select caches quickly, then d to delete the batch; with no selection, d deletes the focused cache. 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, Space to select and advance, a to toggle all visible caches, and d to delete the selection or focused cache. Use / to filter and Tab to cycle scopes. Risky batches use a single compact y/n prompt. Press ? for the complete shortcut guide. Catalog entries marked scan-only are excluded from focused deletion, a batch selection, and CLI cleanup. Select one individually with Space to request a manual override; d then requires confirmation and repeats the safety checks.

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 supports both focused and batch deletion: press Space to build a selection, then d; when nothing is selected, d acts on the focused cache.
• Pressing d remeasures every target before deciding whether confirmation is required. A risky batch gets one confirmation, and every target receives another identity and ownership check immediately before removal.
• 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 from CLI cleanup even with --include-recent --yes. The TUI permits deletion only after individual Space selection and an explicit override confirmation.
• On macOS, CacheFerret recognizes Chrome code-signing clones and strongly identified build caches in system temporary storage. Large temporary project workspaces are visible but scan-only because they may contain unique work; they require the same individual TUI override.
• Temporary caches must remain unchanged between their final measurement and deletion. Active writers cause cleanup to stop with a conflict.
• --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.

Temporary-storage discovery is deliberately narrow. CacheFerret only considers directories owned by the current user, never follows symlinks, and does not treat arbitrary /private/tmp contents as deletable. Recognizable build/cache names are cleanable; large directories with project markers are reported as scan-only diagnostic findings. Global cleanup remains opt-in, and recent temporary entries remain protected unless --include-recent is supplied.

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 docs/product.md for the durable product direction. See 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