Bekas
A safety-first machine audit tool for finding forgotten files, caches, containers, and development artifacts.
- Status
- Completed
- Started
- May 2026
- Role
- Creator and maintainer — plugin architecture, safety model, CLI/TUI, persistence, and packaging.
- Stack
- Python · Click · Pydantic · SQLite · Textual
Reclaim disk space with context, previews, and an undo path instead of trusting a black-box cleaner.
What it is
Bekas scans a machine through a plugin system, explains what it found, and separates discovery from deletion. Audits and plans are read-only; cleaning is dry-run by default and can quarantine supported files before permanent removal.
Why I built it
Developer machines quietly accumulate Docker layers, build directories, virtual environments, package caches, downloads, screenshots, and stale branches. Generic cleaners often lack project context or a trustworthy undo path.
How it addresses the problem
Bekas turns cleanup into an auditable workflow: scan, inspect, plan, then explicitly apply. Candidates carry confidence tiers and reasoning, dangerous paths are excluded, signed plans prevent tampering, and SQLite plus quarantine make supported changes reversible.
What the project actually does
Broad plugin coverage
Scanners cover Docker, Python, Node, Rust, Go, JVM tools, browsers, editors, downloads, screenshots, temporary files, and Git branches.
Read-only first
Audit and plan never change the filesystem, while clean remains a preview until an explicit --apply.
Risk-aware decisions
Every candidate is classified as SAFE, REVIEW, or MANUAL and can be inspected with its reasoning before action.
Reversible cleanup
Quarantine, restore commands, an SQLite undo log, and structured JSONL history keep a record of applied changes.
Efficient repeat audits
Fingerprint-based caching skips unchanged paths and per-plugin timeouts keep one slow scanner from blocking a run.
Extensible core
Third-party scanners can register through Python entry points and declare platform, dependency, safety, and scheduling capabilities.
How the pieces connect
- 01 Plugin scanners
- 02 Candidate model
- 03 Safety tiers
- 04 Signed plan
- 05 Clean / quarantine
- 06 Undo and event log
From zero to a useful result
- 01
Install Bekas
Install it in an isolated Python environment.
pipx install bekas - 02
Audit safely
Run a read-only scan and inspect the candidates Bekas finds.
bekas audit - 03
Preview, then apply
Review a cleanup plan before explicitly applying only the safest candidates.
bekas plan && bekas clean --apply --safe-only
Start from the terminal
pipx install bekas