Files and environment variables

Every file and folder ask-kit reads or writes, and every environment variable it reads.

Sources: src/config.mjs (CONFIG_DIR, STATE_ROOT, callerSession), src/setup/bundle.mjs (TARGETS, installBundle), src/setup/register.mjs (REGISTER), src/server.mjs and src/ask.mjs (state files), and the adapters in src/transcripts/.

The two folders

ask-kit keeps its own files in two folders.

Folder Linux and macOS Windows
Config folder (CONFIG_DIR) $XDG_CONFIG_HOME/ask-kit, else ~/.config/ask-kit %APPDATA%\ask-kit, else ~\AppData\Roaming\ask-kit
State folder (STATE_ROOT) $XDG_STATE_HOME/ask-kit, else ~/.local/state/ask-kit %LOCALAPPDATA%\ask-kit\state, else ~\AppData\Local\ask-kit\state

ASK_KIT_CONFIG and ASK_KIT_STATE replace these paths on every system. macOS uses the Linux paths. Folders are created with mode 0700 and the files below with 0600 where noted.

Config folder

Path Written by Read by Contents
config.json ask-kit setup, apply, add every server and command The config. Written through a temporary file and a rename, mode 0600.
keys.env setup, when you paste a key key lookup NAME=value lines, mode 0600. Config refers to it with { "file", "var" }.
AGENTS.md init, setup, apply, doctor, serve, add agents ask-kit’s guide for agents, rewritten when its text changes, with this machine’s paths and current config. Edits are overwritten.
installed.json init, setup, apply init, uninstall { "files": { "<path>": "<hash>" }, "blocks": { "<path>": true } }: the first 16 hex characters of the SHA-256 of each file ask-kit wrote, and the files holding a marked block. A file whose hash differs is one you edited, and ask-kit leaves it alone.
domains/<name>/ you, or ask-kit add --yes every server Your own domains. A folder here wins over a built-in domain of the same name. Needs a domain.mjs.

State folder

Per domain <d>, the state folder is <STATE_ROOT>/<d>/. The code domain adds one level per repository: <STATE_ROOT>/code/<repository path>/, where the path is the root with leading slashes removed and every other run of characters outside A-Z a-z 0-9 . _ - turned into - (cut at 120 characters). In the table, <state> means that folder.

Path Written by Contents
<state>/<session>.jsonl every server The journal of one session: one line per ask and per cell.
<state>/<session>.snapshot the REPL, after every cell The REPL’s variables, serialized with v8.serialize (mode 0600, at most 64 MB). A follow-up, a restart or a fork restores it.
<state>/drafts/<session>/<name>.mjs scripts.draft Draft scripts an investigator saved.
<state>/warm/<backend>.json claude-cli and codex-cli asks The warm session: { fingerprint, sessionId, warmCostUsd, warmMs }. A new fingerprint (instructions, scripts, API file, server code or backend config changed) re-warms.
<state>/warm/last-<caller>.json every ask Per backend, the investigator to continue: for api, { askId, messages } holding the whole conversation; for the CLIs, the CLI’s session id.
<state>/warm/cwd/ every ask The working directory the agent CLIs run in. Their own transcripts land under it, and the sessions domain leaves any session there out.
<state>/warm/mcp-*.json, copilot-mcp-*.json claude-cli, copilot-cli asks A per-ask MCP config naming the REPL server. Removed when the ask ends.
<STATE_ROOT>/router/<caller>.jsonl the router One line per routed ask: at, question (500 characters), domain, how, routeMs, routeError.
<STATE_ROOT>/router/last-<caller>.json the router { domain, at }: the domain that answered last, for follow-ups.
<STATE_ROOT>/index/<source>.json the transcript adapters A cache of each session file’s metadata (modification time, size, id, title), so a listing does not re-read every transcript. Safe to delete.
<STATE_ROOT>/gallery/<owner>-<repo>/ ask-kit add A shallow clone of a shared domain, replaced on each add.

<session> is the file-safe form of the session id the server runs under. A calling agent’s own server uses the caller’s session id. An investigator’s REPL uses ask-<uuid> for api and Copilot CLI asks. <caller> is the file-safe form of the calling agent’s session id.

ask-kit report reads every .jsonl file under the state folder except in folders named warm, drafts, gallery and index.

Deleting the state folder loses journals, snapshots, warm sessions and drafts. Nothing else.

Files in the agents

ask-kit init and setup write into each agent’s own folder. The base folder moves with the variable shown.

Agent Base folder Skills Tuner agent When-to-ask rule
Claude Code $CLAUDE_CONFIG_DIR, else ~/.claude skills/<name>/SKILL.md agents/ask-kit-tuner.md rules/ask-kit.md
Codex $CODEX_HOME, else ~/.codex skills/<name>/SKILL.md none marked block in AGENTS.md
Copilot CLI $COPILOT_HOME, else ~/.copilot skills/<name>/SKILL.md agents/ask-kit-tuner.md instructions/ask-kit.instructions.md
opencode $XDG_CONFIG_HOME/opencode, else ~/.config/opencode skill/<name>/SKILL.md agent/ask-kit-tuner.md marked block in AGENTS.md
Gemini CLI $GEMINI_CLI_HOME, else ~/.gemini skills/<name>/SKILL.md none marked block in GEMINI.md

The skills are ask-kit-setup, ask-kit-improve and ask-kit-domain. A base folder that does not exist is skipped, so an agent you have not run is left alone. The source files are in bundle/. {{ASK_KIT}} and {{AGENTS_MD}} in them are replaced with this install’s command and guide path.

The ask MCP server is registered in a different file for each agent:

Agent Registration
Claude Code claude mcp add -s user ask -- <node> <ask-kit>/bin/ask-kit.mjs serve (the CLI writes its own config)
Codex A block between # >>> ask-kit and # <<< ask-kit in $CODEX_HOME/config.toml, with tool_timeout_sec = 600 and startup_timeout_sec = 30
Copilot CLI mcpServers.ask in $COPILOT_HOME/mcp-config.json
Gemini CLI mcpServers.ask in ~/.gemini/settings.json, with timeout 600000
opencode mcp.ask in $XDG_CONFIG_HOME/opencode/opencode.json, with timeout 600000

Transcripts read

The sessions domain reads these. It never writes them.

Source Where Moved by
claude-code <base>/projects/<encoded cwd>/<session>.jsonl, top level only CLAUDE_CONFIG_DIR
codex <base>/sessions/YYYY/MM/DD/rollout-*.jsonl and <base>/archived_sessions/rollout-*.jsonl CODEX_HOME
copilot-cli <base>/session-state/<id>/events.jsonl COPILOT_HOME
gemini-cli <base>/tmp/<project hash>/chats/session-*.json GEMINI_CLI_HOME
opencode opencode.db (SQLite, read-only, through node:sqlite) in ~/.local/share/opencode/ OPENCODE_DB, XDG_DATA_HOME

~ is os.homedir() on every system.

The investigator CLIs ask-kit starts (claude -p, codex exec, copilot -p) write their own transcripts in those same stores.

Other files read

Path Read by
~/.config/openrouter/active.env ask-kit detect and setup, looking for OPENROUTER_API_KEY
Any file named by a { "file" } key reference key lookup
The files of the repository under question the code domain, through repo

Environment variables

Where ask-kit keeps things

Variable Meaning
ASK_KIT_CONFIG Replaces the config folder. The tests and the benchmark set it. It is passed on to the investigator’s server.
ASK_KIT_STATE Replaces the state folder. Passed on the same way.
XDG_CONFIG_HOME, XDG_STATE_HOME Linux and macOS: base of the config and state folders. XDG_CONFIG_HOME also moves opencode’s folder.
APPDATA, LOCALAPPDATA Windows: base of the config and state folders.
XDG_DATA_HOME Base of opencode’s database ($XDG_DATA_HOME/opencode/opencode.db).

Which agent’s files to use

Variable Meaning
CLAUDE_CONFIG_DIR Claude Code’s folder: its transcripts, skills, agents and rules.
CODEX_HOME Codex’s folder: transcripts, config.toml, AGENTS.md, skills.
COPILOT_HOME Copilot CLI’s folder: transcripts, mcp-config.json, skills, agents, instructions.
GEMINI_CLI_HOME Gemini CLI’s folder for transcripts, skills and GEMINI.md. Not used for the settings.json registration.
OPENCODE_DB Path of opencode’s database.

Which server runs, and for whom

ask-kit sets most of these itself when it starts a server. You set them to run a server by hand.

Variable Meaning
ASK_KIT_DOMAIN The domain a server runs (sessions when unset). ask-kit serve --domain and the router set it.
ASK_KIT_INNER 1 starts the investigator’s face of the server: the REPL tools, and no ask.
ASK_KIT_SESSION The calling session’s id. ask-kit ask sets shell-<pid> when it is unset. The benchmark sets one per run.
ASK_KIT_CALLER In an investigator’s server: the session it acts for, 1 to 120 characters of A-Z a-z 0-9 . _ : -. A snapshot made for a caller is restored only for that caller.
ASK_KIT_INHERIT In an investigator’s server: the session whose saved variables it starts from when it has none (a fork of a warm session).
ASK_KIT_CODE_ROOT The repository the code domain reads. Default: the git top level of the working directory.
CLAUDE_CODE_SESSION_ID, CODEX_THREAD_ID, CODEX_SESSION_ID, COPILOT_SESSION_ID Read as the calling session’s id when ASK_KIT_SESSION is not set. Agents set them. ask-kit removes all of them, and ASK_KIT_INNER, ASK_KIT_CALLER and ASK_KIT_INHERIT, from the environment of the investigator CLIs it starts.

If none of the session variables is set, the caller’s id is client-<pid of the parent process>.

Timing and logging

Variable Meaning
MCP_TOOL_TIMEOUT The calling agent’s tool timeout in milliseconds, when it sets one. An ask ends 15 seconds before it. ask-kit never sets it.
ASK_KIT_DEBUG Any value: the Ollama path writes each reply, cut short, to stderr.

Keys and services

Variable Meaning
OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY The key of each preset, used when a backend’s key gives none and found by detect.
any name in a { "env" } key reference The variable that reference names.
GITHUB_TOKEN Sent as a bearer token by ask-kit gallery, which avoids the unauthenticated rate limit.
PATH, PATHEXT Finding claude, codex, copilot, gemini, opencode, rg and git. PATHEXT on Windows.

Benchmark only

Variable Meaning
BENCH_QUESTIONS A question file to load instead of bench/questions.json and the private set. See Run the benchmark.

Related: Config file reference, Command line and files, What it stores and sends.