Config file reference

config.json holds what setup decided: which transcripts to read, which agents got the ask tool, which models can investigate, which domains are on, and how the router picks a domain. Setup writes it with ask-kit setup or ask-kit apply. You can edit it by hand. Every server reads it when it starts, so restart your agents after a change; the investigator itself needs no restart.

Where the file lives, per system, is in Files and environment variables. Config never holds an API key. It holds a reference to where a key is.

Source: src/config.mjs (loadConfig, saveConfig, resolveKey), src/setup/apply.mjs (plan, backendFor), src/providers.mjs (API_PRESETS, AGENT_CLIS), src/ask.mjs (registerAsk, endpoint, askApi) and src/router.mjs (makeRouter).

Top-level keys

Key Type Default What it does
version number 1 (written by setup) Written by plan(). Nothing reads it.
sources string[] [] (written by setup) Transcript sources the sessions domain reads. Values: claude-code, codex, copilot-cli, gemini-cli, opencode. An empty list means no source: history sees no sessions. If the key is missing, every source is read.
clients string[] [] (written by setup) Agents that got the ask tool. ask-kit uninstall walks this list to remove the registrations, and the guide (AGENTS.md) prints it.
backends object none, required The models. See backends.
domains object none, required Which domains are on. See domains.
router object or null null when no backend is an API How the router picks a domain. See router.
setupAt string (ISO time) time of setup Written by plan(). Nothing reads it.

loadConfig throws ask-kit is not set up yet when the file is missing, and the server then does not start. A file that is not valid JSON throws with the file name and the parse error.

backends

"backends": { "default": "glm-5.3-flash", "list": { "glm-5.3-flash": { ... }, "codex": { ... } } }
Key Type What it does
default string Name of the backend an ask uses when nothing says otherwise.
list object One entry per backend. The key is the backend’s name: it is what --backend and the tool’s backend parameter take.

The server refuses to start with an empty list (no backends in config).

Which backend answers an ask: the first of these that exists in list:

  1. domains.<name>.backend
  2. the domain’s own defaultBackend (a field a domain module may export; the built-in domains set none)
  3. backends.default
  4. the first entry in list

A backend entry always has a kind. The other keys depend on the kind.

Keys on every backend

Key Type Default What it does
kind "api", "claude-cli", "codex-cli" or "copilot-cli" none, required How the investigator runs. An unknown kind fails the ask with backend <name> has unknown kind.
model string none The model id. For an agent CLI it is passed with --model (-m for Codex) and left out when empty or missing, so the CLI uses its own default. For api it is the model field of the request.

Keys for kind: "api"

Key Type Default What it does
preset string none Key of a preset in API_PRESETS: openrouter, openai, anthropic, gemini, deepseek, ollama, lmstudio, custom. Gives the default baseUrl, key variable and whether the provider reports cost. A name that is not a preset works when baseUrl is set.
baseUrl string the preset’s Base of an OpenAI-compatible API. Requests go to <baseUrl>/chat/completions. Required for the custom preset, which has none. Without a base the ask fails with backend has no baseUrl.
key key reference none Where the API key is. See Key references. When it gives nothing, the preset’s variable (for example OPENROUTER_API_KEY) is tried.
noKey boolean false Send no key and do not fail when none is found. For an endpoint that needs none. The local presets (ollama, lmstudio) never need one.
providerOrder string[] none Sent as provider: { order: [...], allow_fallbacks: true }. OpenRouter reads it to prefer those providers. Setup writes ["DeepInfra"] for z-ai/glm-5.3-flash. ask-kit sends the field to whatever endpoint the backend points at, so use it only with OpenRouter.
nativeTools boolean true true: the model is offered one tool, repl, and calls it. false: the model writes one fenced js block per turn and ask-kit runs the first block. Use false for a model that handles tool calls badly.
explicitCache boolean false Marks the system message with cache_control: { type: "ephemeral" }, for providers that need an explicit cache marker.
contextTokens number 32768 Ollama only (preset: "ollama"). The num_ctx ask-kit asks for through Ollama’s own /api/chat. ask-kit doctor compares it with the model’s limit.

OpenRouter backends also get usage: { include: true } in the request, and a session_id (ask-kit-<domain>-<backend>-<fingerprint>) that keeps a question on one provider so the prompt cache hits. Only OpenRouter reports a cost, so only an OpenRouter backend has a price in the footer and journal.

Keys for agent CLIs

Key Kinds Type Default What it does
bin claude-cli, codex-cli, copilot-cli string claude, codex, copilot The program to run. A path or a name on PATH.
isolate codex-cli boolean true false stops ask-kit passing --ignore-user-config --ignore-rules, so the investigator also loads your Codex config.toml and rules.

claude-cli and codex-cli are warmed once and forked per question. copilot-cli starts fresh each question. See Backends.

Key references

A key reference says where a key is. It has one of these forms:

Form Meaning
{ "env": "NAME" } The environment variable NAME.
{ "file": "~/path/keys.env", "var": "NAME" } The line NAME=value in that file. var defaults to env when both are given. A leading ~ is expanded.
{ "env": "NAME", "file": "...", "var": "NAME" } Both. The variable wins when it is set.

A file holds NAME=value lines. A leading export and quotes around the value are removed. ask-kit setup writes a pasted key to keys.env in the config folder (mode 0600) and stores { "file": "<path>/keys.env", "var": "<PRESET KEY VARIABLE>" }.

Presets

Preset Base URL Key variable Reports cost Local
openrouter https://openrouter.ai/api/v1 OPENROUTER_API_KEY (also looked for in ~/.config/openrouter/active.env) yes no
openai https://api.openai.com/v1 OPENAI_API_KEY no no
anthropic https://api.anthropic.com/v1 ANTHROPIC_API_KEY no no
gemini https://generativelanguage.googleapis.com/v1beta/openai GEMINI_API_KEY no no
deepseek https://api.deepseek.com/v1 DEEPSEEK_API_KEY no no
ollama http://localhost:11434/v1 none no yes
lmstudio http://localhost:1234/v1 none no yes
custom none: set baseUrl none: set key no no

The models each preset suggests are in Choose the model. They are suggestions: model can be any id the provider serves.

domains

"domains": { "sessions": { "enabled": true }, "code": { "enabled": true, "backend": "deepseek-v4.1-flash-1017" } }

The key is a domain name (lowercase letters, digits and dashes, starting with a letter). The router serves every entry whose enabled is not false, so an empty object {} counts as on. A name with no folder fails the router when it starts (no domain "<name>").

Key Type Default What it does
enabled boolean on false takes the domain out of the router and out of the tool’s about list.
backend string none A backend name from backends.list that answers this domain’s asks. Beats backends.default. A name that is not in list is ignored.
from string none Written by ask-kit add: the repository or folder a domain came from.
commit string none Written by ask-kit add: the commit installed.
any other key any none Read by the domain itself. A domain’s makeGlobals({ push, config }) receives the whole config. The notes domain in the how-to reads domains.notes.dir.

ask-kit ask --domain <name> and ask-kit serve --domain <name> start that domain’s server whether or not the config lists it. The config decides only what the router offers.

router

"router": { "backend": "glm-5.3-flash", "model": "z-ai/glm-5.3-flash" }
Key Type Default What it does
backend string none Name of an api backend. The router asks it for one word naming the domain.
model string that backend’s model A different (usually cheaper) model for the routing call. Setup never writes it.

router is null or missing when no backend is an API. Setup sets router.backend to the first api backend in the list: the investigator you chose, else the first extra.

How the router chooses, in order:

  1. The about parameter of the call.
  2. A follow-up (continue: true) goes to the domain that answered last for this caller.
  3. A single enabled domain.
  4. One call to router.backend: temperature 0, 200 tokens, 8 seconds, the question cut at 2000 characters, reply must be one enabled domain name.
  5. Keyword rules, when the call fails or says something else. These test sessions first and then code, and fall back to the first enabled domain.

The router call sends the working directory and the question to the model. See What it stores and sends.

Limits that are not config

These are constants in the code. Change them by editing the source.

Value Where Meaning
20 steps MAX_STEPS in src/ask.mjs Model calls in an api investigation.
60 s CELL_MAX_S The longest one REPL cell may run for an api investigator.
15 s RESERVE_MS Time kept back for the closing “what I found” call, and subtracted from MCP_TOOL_TIMEOUT.
300 s askClaude, askCodex Time allowed to warm an agent CLI session.
4000 characters askApi Result size a cell returns to an api investigator.
4000 tokens, temperature 0 askApi max_tokens and temperature of each api request.
64 MB SNAPSHOT_MAX_BYTES in src/server.mjs Size of the saved REPL variables.

Example

A setup with an API model as the default, a subscription model as an extra, one domain on a different model, and a router:

{
  "version": 1,
  "sources": ["claude-code", "codex"],
  "clients": ["claude-code", "codex"],
  "backends": {
    "default": "glm-5.3-flash",
    "list": {
      "glm-5.3-flash": {
        "kind": "api",
        "preset": "openrouter",
        "model": "z-ai/glm-5.3-flash",
        "providerOrder": ["DeepInfra"],
        "key": { "file": "~/.config/ask-kit/keys.env", "var": "OPENROUTER_API_KEY" }
      },
      "claude-haiku": { "kind": "claude-cli", "model": "haiku" },
      "local-qwen": { "kind": "api", "preset": "ollama", "model": "qwen3.5:9b", "contextTokens": 32768 }
    }
  },
  "domains": {
    "sessions": { "enabled": true },
    "code": { "enabled": true, "backend": "claude-haiku" }
  },
  "router": { "backend": "glm-5.3-flash" },
  "setupAt": "2026-11-18T09:00:00.000Z"
}

Check a hand edit with ask-kit doctor. It lists each source with its session count, each API backend with whether its model id exists at the provider, and the domains and router.

Related: The ask tool, Add a model or provider, Files and environment variables.