Configuration · spec.jev

spec.jev reads pi's settings (models, sign-ins, preferences) and its own, in ~/.spec.jev/agent/spec.jev.json. The desktop app's settings write the same file: every change made there can be made by hand, and vice versa.

Only your own spec.jev.json is read. A project can't change the judge, its address or its modes, because the judge reads your messages.

spec.jev.json

{
  "tiers": ["jev"],
  "modes": {
    "default": "active",
    "turn.continue": "shadow",
    "output.drift": "off"
  },
  "routes": {
    "browser.step": ["jev"],
    "memory.capture": ["laya", "jev"]
  },
  "features": {
    "admission": { "testLog": "rules" },
    "board": { "defaultOn": true },
    "ttsr": false
  },
  "writer": "anthropic/claude-haiku-4-5",
  "recordState": false
}

Key	Meaning	Default
`tiers`	The judges that answer, in order. A later judge only sees what the earlier ones left uncertain.	`["jev"]`
`modes`	`default` plus one entry per decision point: `active`, `shadow` or `off`	`{ "default": "active" }`
`routes`	A decision point on its own judges, in place of `tiers`	none
`judges`	Your own named judges; see Judges	none
`features`	Per-feature switches and options: `false` turns a feature off, an object overrides options. Every option is listed under Features and options.	each feature's defaults
`writer`	A small model, as `provider/model`, for what a judge can't do: writing the task frame and lessons. Empty uses the session's model.	none
`recordState`	Keep the judged state in the ledger, not only the verdict. Needed to train a judge of your own; off because states hold your content.	`false`
`mcp`	spec.jev's own MCP servers: `{ "servers": { "<name>": { "command": … } } }`. Servers from Claude Code, Cursor and Codex are found too.	none

A part spec.jev doesn't understand falls back to its default instead of stopping spec.jev. A file that can't be parsed at all is reported when a session starts, and the defaults are used.

Modes in practice

38 of the 40 points act from the start; context.compact and output.drift stay off until you turn them on. To try a judge, or a point you're unsure of, put it in shadow, read the ledger (spec.jev ledger, /status or the app's Judge tab), then set it back to active.
/mu mode <point> <off|shadow|active> switches one point for the current session; /mu mode default shadow all of them. To keep a mode, put it in spec.jev.json.
SPECJEV_JUDGE_MODE=shadow spec.jev sets the default for one run.

Environment variables

Judges and modes:

Variable	Effect
`SPECJEV_JUDGE`	Judges for this run, comma-separated: `laya`, `laya,jev`, `jev-opencode-free`, `classifier:<provider>/<model>`, `llm:<provider>/<model>`. `off` turns the kernel off.
`SPECJEV_JUDGE_MODE`	Default mode for this run: `off`, `shadow` or `active`
`MU_WRITER`	`provider/model` for the writing model
`MU_PERMISSIONS`	Permission mode for this run: `full`, `jev` or `ask`
`MU_LOCAL_JUDGE_URL`	Address of a local judge server other than the one `spec.jev judge start` runs

Keys for Jev, each sent only to its own service: TYPESAFE_API_KEY, MU_JUDGE_OPENROUTER_API_KEY, AI_GATEWAY_API_KEY, OPENCODE_API_KEY, CLOUDFLARE_API_KEY with CLOUDFLARE_ACCOUNT_ID, MU_JUDGE_CLM_API_KEY.

The launcher:

Variable	Effect
`SPECJEV_AGENT_DIR`	The agent folder, in place of `~/.spec.jev/agent`
`MU_NO_SETUP=1`	Never ask to set up a model at the first start
`SPECJEV_LANG`	spec.jev's own messages in a session: Chinese for `zh…`, English otherwise. The desktop app sets it to the app's language; `spec.jev setup` follows your locale.
`MU_LINK_DIR`	Where `spec.jev link` puts the `spec.jev` command, in place of `~/.local/bin`
`SPECJEV_CHROME`	The Chrome or Chromium the built-in browser uses on the command line

Each MU_ variable is also read under its old KYRN_ spelling.

spec.jev also reads a .env file: ~/.spec.jev/.env for the npm package. Lines are KEY=VALUE; nothing in it is executed. spec.jev setup writes the Jev key there. Variables already set in your environment win.

Proxies

spec.jev follows HTTPS_PROXY, HTTP_PROXY and NO_PROXY. The desktop app also follows the system proxy (macOS network settings, Windows Internet settings) when no HTTPS_PROXY is set. pi's httpProxy setting works as well.

Options people often change

Setting	What it does
`features.admission.testLog`	`"rules"` folds exact repeats in test logs; `"jev"` adds goal-aware selection. Off by default.
`features.board.defaultOn`	Start every project with the plain-language board on
`features.permissions.mode`	The permission mode of a new conversation before you pick one
`features.injection.tools`	Which tools' results are screened for prompt injection
`features.continuation.maxNudges`	How often a run that stopped short is sent back, per message
`features.swarm.models`	Model tiers subagents may be routed to, cheapest first
`features.goal.checkModel`	The model that checks whether a goal holds

Every feature and option, with defaults and ranges: Features and options.

spec.jev.json

Modes in practice

Environment variables

Proxies

Options people often change

If spec.jev is useful to you, star it on GitHub