Developer tooling · 2025 – nowv4 in progress

devDocs

A CLI that documents a whole codebase — now being rebuilt to spend tokens only where they buy understanding.

Role: Design, build and release
When: 2025 – now
Stack: Python (standard library) · SQLite · Gemini · Claude · ast · mypy --strict · PyPI
Links: PyPI Source Write-up

The problem

Why it needed to exist.

Large, old codebases with no documentation turn a new engineer’s first week into archaeology. devDocs came out of exactly that: a legacy project where a one-day task stretched into a week. Version 3 proved the idea. Measuring it showed where the money went — every file, whole, to a strong model — and version 4 is the answer to that measurement.

A command-line tool on PyPI that writes Markdown documentation beside the code. Version 3 is shipped and in use. Version 4, being built now, is a dependency-free engine that plans before it prompts, sends each job to the cheapest model that can do it, and retrieves context across files.

Constraints

The new core imports nothing but Python’s standard library (3.11+): no SDKs to pin, audit or break.
A hard spending ceiling, reserved before each call, and runs that resume where they stopped.
On a free tier the limit is requests, not dollars — v3 needs 618 calls for a 579-file repository, days of daily quota. Fewer calls matter as much as cheaper ones.
No config file required: point it at a repository and go. An optional devdocs.toml can override the defaults.

The system

How devDocs v4 documents a repository

v4, in progress: it scans and parses the repository, a planner picks the files worth a model’s time, a router sends each job to the cheapest capable model under a budget — with a SQLite cache and run ledger, and retrieval for cross-file context — and one document model renders every format.

builtnot built yet

planned“devdocs estimate” shows the requests and the cost first; “devdocs run” spends it, within a ceiling.
A gitignore-aware walk classifies every file; parsers read Python and five more languages.
plannedA zero-token score picks the files worth a model. The rest get accurate stubs from the parser.
Each job gets the cheapest capable model under a hard budget; cached answers make unchanged files free.
plannedRetrieval brings in the neighbouring code a prompt needs; one document model renders Markdown, HTML and PDF.

In use

What it looks like.

devdocs v4 — estimate

$ devdocs estimate .scanned    579 files · ~2.67M tokensplanner    116 files to document · 463 stubs at 0 tokensrouter     flash-lite · flash · pro, by tierestimate   $0.09   (whole-file dump: $1.96)

Illustrative · modelled figuresWhat v4’s dry run is designed to print, before a single paid call.

devDocs v3

$ pip install devDocsSuccessfully installed devDocs-3.0.0$ devDocs --path . --name "Cool Dev Tool"Paste your Gemini API key when prompted.

From the READMEv3 as its README runs it — the version on PyPI today.

devDocs, in the open on GitHub. · captured Sep 2026 from github.com/bgantavya/devDocs

Decisions

Three choices, and what each one cost.

01
Plan before you prompt
Most files in a repository don’t need a model’s prose. Ranking them first — with no tokens spent — means the budget goes to the few that shape how the system works.
Trade-offStubbed files get thinner documentation until someone asks for more.
02
Cheapest capable model first
Every job has a tier — per-file prose, a module summary, or the one or two architecture calls a run makes — mapped to models per provider, cheapest first. A job climbs to a stronger model only when the cheaper one returns nothing usable.
Trade-offTiers need tuning per provider, and prices are data that goes stale — so they carry the date they were checked.
03
Retrieval for quality, not for cost
On its own, retrieval cut the modelled cost by about 5%; routing and planning did the rest. So it is in v4 for cross-file context — call graphs, architecture — not sold as the saving.
Trade-offAn estimated 800 lines for a quality gain — and in prototyping, pure-Python search needed a binary prefilter above roughly 13,000 chunks.

Outcomes

What changed.

downloads on PyPI, all versions: 6.1k; All-time total from pepy.tech, which also counts mirrors and CI installs. Six releases since July 2025.
lower modelled cost per run in v4: 95%; Modelled, not billed: token counts × list prices on a 288k-line corpus (579 files, ~2.67M tokens) — $1.96 for a whole-file dump, $0.09 with routing and the planner. v4 isn’t released yet.
runtime dependencies in the v4 core: 0; Python’s standard library only; an official SDK is an optional extra. Held to ruff, mypy --strict and an 85% coverage floor.

The walkthrough

Watch the walkthroughdevDocs v3 documenting a legacy codebase — Gantavya’s walkthrough.

What I’d do next

The next version.

Finish v4 in the open — the planner, retrieval and the renderers — then ship “estimate” and “run” on PyPI, npm and Docker, with signed releases and a software bill of materials.

Something like this on your plate? Write to me.