Skip to main content

​
Requirements

whyfile post-processes graphify graphs and depends on graphifyy (the graphify runtime that every backend calls), which is installed automatically (ADR-0010). By default it uses a billed API key when one is present (exact prompt tokens, visible cost); with no key it falls back to your Claude Pro/Max subscription via the Claude Code CLI. See LLM backend — including the cost difference — before choosing.

​
Installation

Not a Python project? whyfile is a standalone dev tool — install it the way you install your other CLIs: The LLM backend needs an API key (the preferred default) or the claude CLI (subscription fallback) — see LLM backend. For an API backend, add the provider extra so graphify has its SDK (the subscription backend needs neither):
If the repo wires up the MCP server (an .mcp.json invoking whyfile --mcp), add the mcp extra too — extras don’t imply each other: pip install 'whyfile[bedrock,mcp]'. To enable Pass D’s embedding-based concept resolution, add the optional extra:
Without it, Pass D still runs, degrading gracefully to a lexical-similarity fallback.

​
LLM backend

By default, whyfile uses a billed API key when one is present (ANTHROPIC_API_KEY / GEMINI_API_KEY): an API call sends exactly your prompt, bills per token, and parallelizes fully. With no key it falls back to your Claude Pro/Max subscription through the Claude Code CLI (claude) — read the cost difference below before leaning on that path for large runs. Auto-selection prints a one-line notice saying which backend it picked and how to pick the other. You can also set WHYFILE_BACKEND (the pre-0.5.0 GRAPHIFY_INTENT_BACKEND name was retired). For API mode, install the matching extra (whyfile[anthropic], whyfile[gemini], or whyfile[bedrock], which pull the provider SDK graphify needs) and provide the key — except bedrock, which authenticates through the standard AWS credential chain (env vars / profile / instance role) and needs a region configured, not an API key. For subscription mode, install the claude CLI and run it once to sign in.

​
The cost difference: API vs subscription

The two paths are not equivalent per call, and the reason is structural, so it is worth understanding before you choose: Why it’s this way: claude -p is not a raw model endpoint — it is the Claude Code agent runtime, and subscription (OAuth) auth only exists through it. Every invocation carries some of the agent’s own context. whyfile strips everything strippable — it invokes the CLI with the built-in tool schemas disabled, its own per-pass system prompt in place of the agent prompt, no MCP config, and an empty working directory — which cuts the measured overhead from ~36k to ~3k input tokens per call (the CLI’s --bare flag would go further but disables OAuth, so it cannot serve subscription users). That ~3k floor is irreducible from outside the CLI. Set WHYFILE_CLI_LEAN=0 to restore the un-stripped path if you need the CLI’s default behavior. The practical guidance: for real runs, prefer an API key — exact tokens, a visible dollar figure, and two layers of protection: the pre-run estimate you approve, plus a measured mid-run guard (--max-tokens / --max-cost-usd) that stops the run on the provider’s real token counts if actual spend outruns that estimate. The subscription path is genuinely useful for zero-config first runs and small corpora; just know that each call carries the overhead above against your plan’s weekly limits, and check intent_run.json’s per-pass tokens_in (measured from the provider, not estimated) to see exactly what a run drew. See What a run costs.

​
Keep API keys out of .env and your shell history

If you do use an API key, prefer a password-manager CLI over inlining the secret. With 1Password’s op, inject it at runtime so it never lands on disk in plaintext:
…or wrap the command with op run so the secret lives only for that process:
A real key committed in .env risks leaking into git history, CI logs, and backups; a manager keeps it encrypted, access-audited, and revocable. (The subscription fallback needs no key at all — see the cost difference above before choosing it for large runs.)

​
graphify runtime dependency

Every backend routes through graphify’s graphify.llm, so whyfile declares graphifyy as a runtime dependency; pip install whyfile installs it (ADR-0010). For an API backend, add the provider extra so graphify’s SDK is present:
The subscription fallback needs no provider SDK, only the Claude Code CLI (claude), installed and signed in. If the graphify runtime is somehow missing, whyfile exits immediately with a clear install message rather than failing deep inside a run.