whyfile

Your codebase remembers what it does. It forgot why.

whyfile extracts the decisions, constraints, and trade-offs behind your code into a queryable graph, anchored to the code they govern — then lets you ask why your code looks the way it does.

This npm package is a thin launcher. The tool itself is a Python CLI published on PyPI; this shim runs it through uv, which provisions its own Python — so you don't need Python installed to use it.

Usage

npx whyfile --help

…or put it on your PATH:

npm i -g whyfile

On first run, if uv isn't found, whyfile prints the one-line command to install it. uv brings its own Python, so nothing else is required on the machine — except the LLM backend the tool uses for its analysis passes (your claude CLI subscription by default, or an API key).

Under the hood this launcher simply runs uv tool run whyfile@<version> and forwards your arguments, exit code, and signals. It never downloads or caches anything itself.

Links

• Docs & source: https://github.com/whyfile/whyfile
• PyPI package: https://pypi.org/project/whyfile/
• Changelog: https://github.com/whyfile/whyfile/blob/main/CHANGELOG.md