Environment variables

Every environment variable hunch and hunch-server read, with its default and effect.

API keys

Only the key for the spec’s engine, and only when an answer is not in the store.

Variable	Used by	Effect
TYPESAFE_API_KEY	model: jev-…	The TypeSafe key for Jev.
TYPESAFE_AI_API_KEY	model: jev-…	Read if TYPESAFE_API_KEY is not set.
DEEPSEEK_API_KEY	model: deepseek:<id>, and hunch suggest with the default writer	The DeepSeek API key.
OPENROUTER_API_KEY	model: openrouter:<id>	The OpenRouter API key.

A missing key stops the command before anything is sent: command_guard: set TYPESAFE_API_KEY to ask jev-1.13.0 (38 requests to send).

hunch

Variable	Default	Effect
HUNCH_STORE	unset	Path of the SQLite store to use. When unset, hunch uses the nearest .hunch/store.sqlite in the spec’s folder or above, or creates one at the git repository root. See Store.
HUNCH_MAX_COST	unset (no cap)	The most one set of asks may be charged, in US dollars (a judgment’s missing answers; its escalations and test’s order check are separate sets): nothing is asked if the estimate is above it, and a request is sent only if its worst case still fits. --max-cost overrides it on the CLI. Read once when hunch is imported.
HUNCH_CONCURRENCY	16	Requests in flight at once for each judgment. The 100,000-row test ran at 32 with no rate-limit errors. Read once at import.
FASTEMBED_CACHE_PATH	~/.cache/hunch/encoders	Where hunch distill and distilled: models keep the encoder they download once (about 90 MB).
NO_COLOR	unset	Any value turns off bold and dim text on the hunch review screen. Output is also plain when it is not a terminal.
GITHUB_STEP_SUMMARY	set by GitHub Actions	When set, hunch test also appends a Markdown table of its results to this file, which GitHub shows on the run’s summary page. See Test in CI.

hunch-server

Variable	Default	Effect
HUNCH_PROJECTS	the current folder	The folder every request path is relative to. Paths that resolve outside it are refused.
HUNCH_SERVER_TOKEN	unset (open server)	The token every request must carry. See authentication.
HUNCH_SERVER_MAX_COST	0.01	The cost cap for answers the server asks for, per judgment per request, in US dollars. It replaces HUNCH_MAX_COST inside the server.

The server also reads HUNCH_STORE, HUNCH_CONCURRENCY and the API keys, like the CLI.