Whyfile reconstructs the reasoning behind your code — what was decided, what got tried and thrown away, the constraint the awkward bit is quietly paying for — before the person who could explain it is gone.
Orphan cache entries accumulate, with no automatic pruning.
Whyfile's own inference — a good guess, never gospel. Marked as such, so it can never outrank the record.
Every project has a file for how. None of them have one for why.
It reads your design notes and decision records alongside a structural graph of the code,
and rebuilds the reasoning that never became a comment because nobody writes
# WHY: above the thing they decided not to do.
Decisions, dead ends, and the constraints the awkward bits are quietly paying for — extracted into a queryable graph and anchored back to the exact code they govern.
Every unit is tagged authored (a human recorded it) or reconstructed (a model inferred it), grounded to its source span — so a guess never poses as a decision you made.
The gate fails a pull request that changes constraint-governed code without conforming to the constraint, or explicitly superseding the decision behind it.
The one thing Whyfile is almost obsessive about: never letting its own best guess pass as a fact someone actually wrote down. Every answer says, plainly, which kind it is.
A person recorded this, on purpose — in an ADR, a decision record, a Why: commit trailer. Trusted evidence. It counts toward your golden fraction.
Whyfile's best inference from the surrounding record. Useful, never gospel — shown separately, and it never inflates the trusted count.
Surfacing rationale that's written down is table stakes. The change conforms to each recorded constraint, or the same PR supersedes the decision out loud. Silently breaking a decision the code is built on is not a path the merge leaves open.
Nobody breaks a promise they didn't know existed.
Three commands read the intent layer back with no backend call and no cost. The month of code archaeology every new hire does — done once, checked in.
Why is this file like this? The intent that motivates it.whyfile explain cache.py
Rank recorded intent against a plain-English question.whyfile why "why serialize here?"
The same query layer, one tool call away in Claude Code, Cursor, or any IDE agent.whyfile --mcp
For teams whose codebase has outlived somebody's memory of it. No API key required — it runs on your Claude Pro/Max subscription by default.