A backend is a named model that can act as the investigator: a chat API that ask-kit drives itself, or an agent CLI you already have. The config file lists them, and each ask runs on one. This page covers where backends are defined, where their keys live, how one is picked, and how the CLI investigators are kept to the REPL.
Files
| File | What is in it |
|---|---|
| src/providers.mjs | API_PRESETS (chat APIs: base URL, key variable, suggested models), AGENT_CLIS (claude, codex, copilot), AGENTS (agents whose transcripts and MCP settings ask-kit knows). |
| src/config.mjs | CONFIG_DIR, STATE_ROOT, CONFIG_FILE, KEYS_FILE, loadConfig, saveConfig, storeKey, resolveKey, readEnvFile, callerSession, slug. |
| src/ollama.mjs | ollamaChat (OpenAI request in, OpenAI reply out, over Ollama’s /api/chat), OLLAMA_DEFAULT_CTX, ollamaContextLength. |
| src/ask.mjs | registerAsk: DEFAULT, endpoint, askApi, claudeArgs, CLAUDE_DENY, codexArgs, askCopilot’s flags. |
| src/platform.mjs | which, spawnCli, runCli: starting CLIs, including Windows .cmd shims. |
| src/setup/apply.mjs | backendFor, backendName, plan: how setup turns an answer into a config entry. |
| src/setup/questions.mjs | investigatorChoices: which presets and models setup offers. |
| src/setup/detect.mjs | Finds API keys (keyEnv, keyFiles, keys.env), CLIs on PATH and local model servers. |
The config file
Setup writes ~/.config/ask-kit/config.json (CONFIG_FILE). ASK_KIT_CONFIG moves the folder and
ASK_KIT_STATE moves the state folder; the tests use both. On Windows the folders are under
%APPDATA% and %LOCALAPPDATA%. loadConfig throws a “not set up yet” error when the file is
missing. saveConfig writes a temporary file and renames it, mode 0600.
The fields the code reads:
{
"version": 1,
"sources": ["claude-code", "codex"],
"clients": ["claude-code"],
"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" }
}
},
"domains": { "sessions": { "enabled": true }, "code": { "enabled": true, "backend": "claude-haiku" } },
"router": { "backend": "glm-5.3-flash" }
}
The shape above comes from plan() in src/setup/apply.mjs and from the places that read it.
Config reference lists every field.
Backend entry fields
Every entry has kind. The other fields, as src/ask.mjs reads them:
| Field | Kinds | Effect |
|---|---|---|
kind |
all | api, claude-cli, codex-cli or copilot-cli; picks the function in KINDS. |
model |
all | Sent as model (api), --model (claude), -m (codex), --model (copilot). Empty means the CLI’s own default. |
bin |
CLIs | Program to run instead of claude, codex or copilot. |
preset |
api | A key of API_PRESETS. |
baseUrl |
api | Overrides the preset’s base URL. custom has none, so it must be set. |
key |
api | A key reference; see below. |
noKey |
api | Allows a non-local endpoint with no key. |
nativeTools |
api | false switches the loop to code-block mode. Default is native tool calls. |
explicitCache |
api | Sends the system prompt with cache_control: ephemeral. |
providerOrder |
api | OpenRouter only: provider: { order, allow_fallbacks: true }. |
contextTokens |
api, Ollama | num_ctx for Ollama; default OLLAMA_DEFAULT_CTX (32768). |
isolate |
codex-cli | false keeps the user’s own Codex config and rules; see below. |
Keys
Config never holds a key. A backend’s key is a reference that resolveKey in config.mjs
resolves at the time of the call:
{ "env": "NAME" }: the environment variable, if it is set.{ "file": "path", "var": "NAME" }: the variable in that env-style file (readEnvFileacceptsNAME=valueandexport NAME=value, with optional quotes, and expands~).- Both: the environment wins.
When a backend has no key, endpoint() in ask.mjs falls back to the preset’s keyEnv
variable (OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY,
DEEPSEEK_API_KEY). With no key and a non-local preset (and no noKey) it throws
no API key for <label>: ... is empty.
keys.env (KEYS_FILE, ~/.config/ask-kit/keys.env) holds keys the user pasted during setup.
storeKey(name, value) writes NAME=value lines with mode 0600 and returns the
{ file, var } reference that config keeps. Keys that were found elsewhere (an environment
variable, or a preset’s keyFiles, which for OpenRouter is ~/.config/openrouter/active.env) stay
where they were; detect.mjs records where, and setup stores that reference.
The router resolves its key the same way (byModel in src/router.mjs).
How a backend is chosen
In registerAsk:
const DEFAULT = [domainCfg.backend, D.defaultBackend, config.backends.default, NAMES[0]].find((b) => b && BACKENDS[b]);
config.domains.<name>.backend, to put one domain on a different model.- The domain module’s
defaultBackend. config.backends.default.- The first name in
backends.list.
A caller’s backend argument overrides all of them for that ask. The router passes it through
without checking; the domain server validates it against the list (z.enum(NAMES)). A
follow-up with continue: true uses the saved state of the backend that is chosen, so a
different backend on a follow-up has nothing to continue
(nothing to continue: no earlier <backend> question in this session).
The router’s own model is separate: config.router.backend must name an api backend, and
config.router.model can override its model. plan() sets router.backend to the first API
backend in the list, or null when there is none.
API backends
API_PRESETS has openrouter, openai, anthropic (through its OpenAI-compatible endpoint),
gemini, deepseek, ollama, lmstudio and custom. Each has label, baseUrl, keyEnv and
a models list (suggestions, cheapest first). Two flags change behaviour in ask.mjs:
reportsCost(OpenRouter only):costUsdis taken fromusage.costin the replies. Other presets reportcostUsd: null, so the footer shows no cost.local(Ollama and LM Studio): no key needed.
The loop posts to <baseUrl>/chat/completions. The body has model, messages,
temperature: 0, max_tokens: 4000, and with native tools tools, tool_choice: "auto" and
parallel_tool_calls: false. Life of one ask has the loop.
Ollama
Ollama’s /v1 endpoint takes no context size, so prompts are cut at its 4096-token default, and
the investigator’s fixed prefix is about 7000 tokens. When preset is ollama, askApi calls
ollamaChat instead of fetch. It translates the OpenAI request to Ollama’s /api/chat
(arguments parsed to objects, think: false so the answer is not written into thinking,
options.num_ctx, num_predict from max_tokens) and the reply back to the OpenAI shape
(finish_reason is length when Ollama reports done_reason: "length"; usage maps to
prompt_tokens and completion_tokens). ASK_KIT_DEBUG prints each raw reply to stderr.
ollamaContextLength reads a model’s maximum from /api/show; ask-kit doctor uses it to warn
when the model’s maximum is below the context ask-kit requests. LM Studio uses the plain fetch path.
How the CLI investigators are limited
A CLI investigator must work through the REPL and nothing else. Each kind does that with its own flags
(all in src/ask.mjs):
claude-cli (claudeArgs):
--strict-mcp-config --mcp-config <file>: only thereplserver, from a temporary JSON file written per call and deleted afterwards. The user’s own MCP servers are not loaded.--disallowedToolswithCLAUDE_DENY:Bash,Read,Grep,Glob,Edit,Write,NotebookEdit,WebFetch,WebSearch,Agent,Task,Skill,TodoWrite.--append-system-prompt-file <instructions>and--permission-mode bypassPermissions, so the REPL tools run without a prompt that nobody could answer.- The working directory is
STATE_DIR/warm/cwd, an empty folder.
codex-cli (codexArgs):
-s read-onlyand-C <warm cwd>,approval_policy="never".--ignore-user-config --ignore-rules, unless the backend hasisolate: false: the user’s ownconfig.tomlwould otherwise add their MCP servers and instructions. Authentication is inauth.jsonand is kept.- The
replserver is defined with-c mcp_servers.repl.*(command, args, environment),tool_timeout_sec=180anddefault_tools_approval_mode="approve". - The prompt tells it to use only the
repltool. Nothing stops Codex using its shell inside the read-only sandbox; the sandbox is what limits it. - Forks and resumes drop
-sand-Cfrom the arguments (the filter inaskCodex). The code does not say why; the likely reason is thatexec forkandexec resumedo not accept them.
copilot-cli (askCopilot):
--additional-mcp-config @<file>with--disable-builtin-mcps,--no-custom-instructionsand--no-ask-user.--allow-all-toolswith--deny-tool shelland--deny-tool write.-sand--output-format json; each question starts a new session unless it is a follow-up.
All three run through runCli in platform.mjs, which starts the program with no stdin, collects
stdout and stderr, sends SIGTERM on timeout or abort, and never rejects (it returns code, out
and err). childEnv removes the session variables (ASK_KIT_SESSION, CLAUDE_CODE_SESSION_ID,
CODEX_THREAD_ID and others) from the CLI’s environment so the investigator’s REPL cannot write
into the asking agent’s own state.
Where to look when changing it
- Change a suggested model or its note: the
modelslist of the preset insrc/providers.mjs. Setup offers the first one. Existing configs keep what they have; editconfig.json, or runask-kit setupagain. - Add an API provider that speaks the OpenAI chat format: add an
API_PRESETSentry (label,baseUrl,keyEnv,models, andreportsCostorlocalif they apply). Setup anddetect.mjspick it up from the table. Check how it handlestool_choiceandparallel_tool_calls; if it rejects tools, setnativeTools: falsein a backend entry. - Add a new kind of backend (another agent CLI, a different protocol): a function in
ask.mjsand an entry inKINDSandAGENT_CLIS, plus detection and setup choices. Add a backend goes through it. - Change what a CLI may do:
CLAUDE_DENY,codexArgsand the flags inaskCopilot. Run a real ask on that CLI afterwards; the flags change between CLI releases and no test covers them. - Keys:
resolveKey,storeKeyandreadEnvFile. Keep the rule that config never holds a key (test/bundle.mjsasserts it). - Change how the default is chosen: the
DEFAULTline inregisterAsk.
Tests: test/setup.mjs checks backendName, that plan() stores key references and sets
router.backend, and that a pasted key lands in keys.env with mode 0600 and not in the config.
test/bundle.mjs repeats the keys check after two applies. test/repl.mjs builds a config with an
ollama API backend to start the server. Nothing in test/ calls the provider endpoints or the
CLIs, so a change to askApi or a CLI’s flags needs a real ask on that backend (and the benchmark
for anything that changes what the model sees). See Testing.