DevDoctor scans the caches, model weights, containers, virtualenvs, and leftover git worktrees quietly eating your disk — then cleans them up on your terms. Diagnosis first. Nothing deleted until you say so.
$ uv tool install git+https://github.com/katagun/devdoctor
Two problems, one tool: the disk that keeps filling up, and the RAM that keeps running out. DevDoctor measures both, explains what it found, and only acts with your sign-off.
One command surfaces every known cache — Docker layers, model weights, build artifacts, virtualenvs — sized accurately with symlink-safe, hard-link-deduped walks. Sorted biggest first.
See live memory pressure and the top consumers — browsers, Electron apps, Docker, local LLM runners — with one-click actions to quit the app or stop the container that's swapping your machine to a crawl.
clean defaults to a dry run: zero prompts, zero shell commands. Every entry is labelled safe, reclaimable, or dangerous — and dangerous ones are skipped unless you opt in.
Snapshot usage before a cleanup, then diff two points in time — or against live — to see exactly what each cache reclaimed and how your disk trends over weeks.
Rich terminal tables with JSON output for scripting and a local web dashboard with a live cleanup wizard — both shipping now, with a hardened desktop app on the way. Same engine underneath.
No telemetry, no accounts, no network calls. The web UI binds to loopback only, guarded against DNS-rebinding, and commands run as argv lists — never through a shell.
A third of what's "used" is cache you'd never miss. DevDoctor finds it before your disk hits the red.
Sparse files like Docker.raw report 80 GB but use megabytes. DevDoctor measures real on-disk blocks, stays on one device, and counts hard-linked model files once — so the numbers you act on are the numbers that free up.
When everything slows to molasses, DevDoctor names the culprit — the browser with 200 tabs, the idle Docker daemon, the LLM runtime still holding a model in RAM — and offers the safe way to stop it. It even re-checks the process is still the one you meant before it signals anything.
Run the memory scan →Measured on one developer's machine: 150 worktrees, 39 of them provably removable. Yours will differ, and footprint is never counted as reclaimable.
Many coding agents check out a fresh git worktree for every task, and each one carries its own node_modules, virtualenv and build output. DevDoctor finds every worktree that repositories under your project roots register and proves which ones can go: integrated into the default branch, squash and rebase merges included (git 2.38+), with no uncommitted changes and nothing nested inside. Only those are offered, through git worktree remove and never --force. Everything else stays advice.
Especially AI-assisted work: model weights and agent worktrees are the new disk sinks. DevDoctor ships with providers for the usual offenders, plus a YAML-driven list you can extend for anything else.
rm -rf.Destructive tools earn trust by refusing to be reckless. DevDoctor is built so the dangerous path is always the deliberate one.
clean shows what it would remove and stops. No prompts, no shell calls. You opt into action with --execute, then confirm each entry and a final summary.
recipe writes a shell script with every destructive line commented out. Read it, uncomment what you want, run it yourself. No surprises hidden in an abstraction.
Commands execute as argv lists — never through a shell — with every path safely quoted. A filename with a quote or $(…) in it is inert data, not an injection.
A single Python core drives every surface, so a scan means the same thing whether you typed it or clicked it. The CLI and web UI ship today; the desktop app is in progress.
Rich tables sorted by size, with --json for pipelines and filters for size and risk.
scan — see every cache at a glanceclean --execute — interactive cleanupsnapshot / diff — track over timeLaunch serve for a local dashboard: treemaps, a step-by-step cleanup wizard, and live progress streamed as each command runs.
A hardened Electron desktop app is in the works — double-click to launch, no terminal required. It's not released yet; for now, use the CLI or the web UI.
Hugging Face, Ollama, and LM Studio each keep their own multi-gigabyte copies. DevDoctor sums the true cost across all three — including the HF cache LM Studio points into — so you can clear what you're not using.
Out of room mid-compile or ahead of an OS update? One scan, sort by size, clean the safe and reclaimable entries, and watch the free-space number climb — with a snapshot to prove what it recovered.
The memory advisor ranks live consumers by real RSS and flags the pressure state, then offers to quit the app or stop the container — the safe fix, not a guessed kill.
Auto-snapshots capture usage over time. Diff any two points — or against live — to see which caches keep growing back and decide what deserves a permanent spot on your ignore list.
An end-to-end tutorial from a real 14 GB → 70 GB cleanup, plus reference for every command, provider, and API endpoint. The same content lives as Markdown in docs/ in the repo.
Scan, read the report, handle Docker and Time Machine, preview, then clean the safe tier — step by step.
Every command and flag, plus the scan --json contract for pipelines and agents.
What each of the 70+ providers covers and its risk level — safe, reclaimable, or dangerous.
The agent contract: read-only scan, rules for --execute, reading the JSON. Also served as llms.txt and llms-full.txt.
Requires Python 3.12+ on macOS or Linux. Install with uv and you're diagnosing immediately.
$ uv tool install git+https://github.com/katagun/devdoctor
$ uv tool install "devdoctor[web] @ git+https://github.com/katagun/devdoctor"