This part of the code finds what a machine has, asks the questions, writes ask-kit’s config,
registers the ask server with each coding agent, installs the skills, agent and rule, writes the
per-machine guide and reports on how ask is doing. The commands are init, questions,
apply, setup, doctor, detect, uninstall and report. For the user’s view see
Set it up and Command line.
Files
| File | What is in it |
|---|---|
| bin/ask-kit.mjs | The command switch in main(), and the functions wizard() (setup), init(), uninstall(), doctor(), summary() and printDetect(). |
| src/setup/detect.mjs | detect({counts}): agents, subscription CLIs, API keys (by name), local model servers and tools. |
| src/setup/questions.mjs | questions(d), investigatorChoices(d), keyQuestion(preset). The answers format is in the header comment. |
| src/setup/apply.mjs | plan(answers, d) (pure), apply(answers, d, {dry}), backendName(id), and the private backendFor. |
| src/setup/register.mjs | REGISTER: one function per agent returning {client, what, run(), remove()}. SERVE is the command an agent starts. |
| src/setup/bundle.mjs | TARGETS (where each agent keeps skills, agents and rules), filesFor, render, installBundle, uninstallBundle, and the MARK and MANIFEST constants. |
| src/providers.mjs | API_PRESETS, AGENT_CLIS, AGENTS: the data detection and the questions are built from. |
| src/agentsmd.mjs | AGENTS_MD, agentsMd() (the text), writeAgentsMd(). |
| src/config.mjs | CONFIG_DIR, STATE_ROOT, CONFIG_FILE, KEYS_FILE, loadConfig, saveConfig, storeKey, resolveKey, readEnvFile. |
| src/platform.mjs | which, spawnCli, runCli, rgPath. |
| src/report.mjs | report({since}). |
| bundle/ | rules/ask.md, agents/ask-kit-tuner.md, skills/ask-kit-setup/SKILL.md, skills/ask-kit-improve/SKILL.md, skills/ask-kit-domain/SKILL.md. |
| AGENTS.md | The install instructions an agent reads from GitHub, before ask-kit is installed. |
| test/setup.mjs, test/bundle.mjs | The tests. |
Where ask-kit keeps things
src/config.mjs decides, once at import. src/platform.mjs does not hold paths; it holds program
lookup and process starting.
| Constant | Linux and macOS | Windows | Overridden by |
|---|---|---|---|
CONFIG_DIR |
$XDG_CONFIG_HOME/ask-kit, else ~/.config/ask-kit |
%APPDATA%\ask-kit |
ASK_KIT_CONFIG |
STATE_ROOT |
$XDG_STATE_HOME/ask-kit, else ~/.local/state/ask-kit |
%LOCALAPPDATA%\ask-kit\state |
ASK_KIT_STATE |
CONFIG_FILE |
CONFIG_DIR/config.json |
same | |
KEYS_FILE |
CONFIG_DIR/keys.env |
same |
Other files: CONFIG_DIR/installed.json (the bundle’s record), CONFIG_DIR/AGENTS.md (the
guide), CONFIG_DIR/domains/ (your domains) and STATE_ROOT/ (journals, REPL snapshots, warm
sessions, the transcript index, gallery/ clones).
The agents’ own folders are separate and each has its own variable: CLAUDE_CONFIG_DIR,
CODEX_HOME, COPILOT_HOME, GEMINI_CLI_HOME, OPENCODE_DB, and for opencode’s config
XDG_CONFIG_HOME, for its database XDG_DATA_HOME.
XDG_CONFIG_HOME, XDG_STATE_HOME and XDG_DATA_HOME take precedence over HOME. On a
machine where they are set (most Linux desktops), running ask-kit with a different HOME and
nothing else still reads and writes the real config, state, opencode config and opencode
database. To test without touching a real machine, set ASK_KIT_CONFIG and ASK_KIT_STATE
and every agent variable the test touches, as test/setup.mjs and test/bundle.mjs do. Also
note that os.homedir() reads HOME on Linux and macOS, so ~ in the key-file list of an API
preset follows HOME but not XDG_CONFIG_HOME.
detect: what the machine has
detect({counts}) in src/setup/detect.mjs returns {agents, clis, apis, local, tools, existing}. It runs programs and probes ports, so it is not free of side effects.
- agents: for each entry of
AGENTSit looks the binary up withwhich()(a search ofPATHthat handlesPATHEXTon Windows). If the binary is found it runs<bin> --versionwith a 6-second timeout.onPathis true only when that command exits with status 0. A binary that is found but fails (a version manager’s shim with no version set) is reported withbrokenandonPath: false. It also records the transcript store (adapter.where()whenadapter.available()) and, withcounts, the number of sessions, which builds the transcript index cache. - clis: the agent CLIs that can act as the investigator (
AGENT_CLIS:claude,codex,copilot), whether the binary is onPATH, and whether it is signed in:claude auth status(JSON),codex login status. Copilot has no status command, so it is reported asokwith the status text “not checked”. - apis: for each non-local preset in
API_PRESETS, whether its key variable is set in the environment, in one of the preset’skeyFiles, or inkeys.env. It stores where, never the value. - local:
GET <baseUrl>/modelson Ollama and LM Studio, with an 800 ms timeout. - tools: Node version (
nodeOkmeans 22.13 or newer),rgPath(),which("git"), platform. - existing: the parsed
config.jsonif one exists.
ask-kit detect prints it (--json for the data). ask-kit questions runs it with counts and
prints summary(d), the questions and existing.
questions: the conversation
questions(d) builds five questions in this order: sources, clients, investigator,
extras, domains. Each has id, type (multi, single), question, why, options and
suggested. The terminal wizard and an agent running the ask-kit-setup skill ask the same
questions.
sourceslists agents that have a transcript store.clientslists agents that are onPATHand whoseAGENTSentry has aclient(opencode hasclient: null, so it is never offered).investigatorChoices(d)makes one choice per model: each API preset model, each agent CLI model, and each model a local server reports (embedding, reranking, OCR and whisper models are filtered out). Therankfield orders them: ready API models first (OpenRouter before others), then CLIs (Claude, Codex, Copilot), then local models. The suggestion is the first ready choice.extrassuggests up to two more ready choices, never a Copilot one.domainsofferssessionsandcode, both suggested.keyQuestion(preset)is asked separately, only for an API without a key found.
Choice ids look like openrouter:z-ai/glm-5.3-flash or claude-cli:haiku.
apply and setup: answers to config and registrations
ask-kit apply <file|-> reads answers as JSON, runs detect({counts: false}) and calls
apply(answers, d, {dry}). ask-kit setup (wizard()) asks the questions on a terminal, shows
apply(..., {dry: true}), and applies on a yes. --dry-run prints {config, changes, applied: []}
and writes nothing.
plan(answers, d) is pure apart from what the registrations read:
-
The backend list:
answers.investigatorfirst, thenanswers.extras.backendName(id)makes the key (claude-haiku,codex,glm-5.3-flash),backendForthe value:{kind: "claude-cli", model}for a CLI, or{kind: "api", preset, model, key}for an API. A pasted key becomes the marker{value: true}; a named variable or file is kept as{env}or{file, var}; otherwise the first key found bydetectis used; with none it throws. -
The config object:
{ version: 1, sources, clients, backends: { default, list }, domains, router, setupAt }domainsis{ <name>: { enabled: true } }for each name inanswers.domains(defaultsessionsandcode).routeris{ backend: <name> }for the first API backend in the list, ornull. -
changes: write the config, oneREGISTER[client]()per chosen client that has a registrar, and one bundle install (computed withinstallBundle(clients, {dry: true}), listed only when something would change).
apply() then, in order: replaces each {value: true} key by storeKey() (which writes
keys.env, mode 0600, and returns {file, var}); saveConfig() (temporary file, mode 0600, then
rename); writeAgentsMd(); and runs each change, catching its error into
applied: [{client, what, ok, error?}]. A failed registration does not undo the config.
Config never holds a key. resolveKey(ref) reads {env} or {file, var} at use.
Registering ask: REGISTER
SERVE is {command: process.execPath, args: [<root>/bin/ask-kit.mjs, "serve"]}: the absolute
path of the Node that ran setup. Each registrar returns an object with what (shown to the user),
run() and remove(). The entries are built when plan runs, so some read the machine at that
point.
| Agent | What it writes |
|---|---|
| Claude Code | Runs the claude CLI: claude mcp get ask to see if it exists, then claude mcp add -s user ask -- <node> <bin> serve (after remove when it exists). |
| Codex | A marked block in $CODEX_HOME/config.toml (default ~/.codex): [mcp_servers.ask] with tool_timeout_sec = 600 and startup_timeout_sec = 30. The markers are # >>> ask-kit ... and # <<< ask-kit. If an [mcp_servers.ask] exists outside the markers, it is left alone and the entry says skip. |
| Copilot CLI | mcpServers.ask in $COPILOT_HOME/mcp-config.json (default ~/.copilot). |
| Gemini CLI | mcpServers.ask in ~/.gemini/settings.json, with a 600 s timeout. It uses the home folder directly, not GEMINI_CLI_HOME. |
| opencode | mcp.ask in $XDG_CONFIG_HOME/opencode/opencode.json (default ~/.config/opencode). |
jsonServer() reads the file (an unreadable or missing file counts as {}), sets the key and
writes it back, with two-space indentation.
The bundle: skills, agent and rule
bundle/ holds one source of each file. installBundle(agents, {dry, force}) renders it into
each agent’s own format and folder, driven by TARGETS:
| Agent | Base folder | Skills | Agent file | Rule |
|---|---|---|---|---|
| Claude Code | CLAUDE_CONFIG_DIR or ~/.claude |
skills/ |
agents/ (as is) |
rules/ask-kit.md, a file |
| Codex | CODEX_HOME or ~/.codex |
skills/ |
none | a marked block in AGENTS.md |
| Copilot CLI | COPILOT_HOME or ~/.copilot |
skills/ |
agents/ (name and description only) |
instructions/ask-kit.instructions.md, with applyTo: "**" front matter |
| opencode | $XDG_CONFIG_HOME/opencode or ~/.config/opencode |
skill/ |
agent/ (description, mode: subagent) |
a marked block in AGENTS.md |
| Gemini CLI | GEMINI_CLI_HOME or ~/.gemini |
skills/ |
none | a marked block in GEMINI.md |
opencode and Gemini have verified: false: the format comes from the agent’s documentation.
render(text) replaces {{ASK_KIT}} (the Node path plus bin/ask-kit.mjs) and {{AGENTS_MD}}
(the guide’s path) in every file, so a skill names the exact command for this machine.
filesFor(agent) reads bundle/skills/*/SKILL.md, bundle/agents/*.md and bundle/rules/ask.md.
Hash tracking in installed.json
MANIFEST is CONFIG_DIR/installed.json: { files: { <path>: <hash> }, blocks: { <path>: true } }.
The hash is the first 16 hex digits of the SHA-256 of the content ask-kit wrote. For each file
installBundle compares the file on disk with the new content and the recorded hash:
| State | Action |
|---|---|
| File missing | write |
| Content equals the new content | unchanged (the hash is recorded, which adopts a matching file) |
| Differs, no hash recorded | skip-not-ours, or replace with force |
| Differs, hash matches the file on disk | replace: still as ask-kit wrote it, so update it |
| Differs, hash does not match | skip-edited, or replace with force |
An agent whose base folder does not exist gets one row, skip-no-agent, and nothing is written.
Rules in file mode use the same table. Rules in block mode are written between
<!-- >>> ask-kit: written by ... --> and <!-- <<< ask-kit -->. The block is added when the
markers are absent (block-add) and replaced in place when present (block-replace), whatever
was edited inside it; the file’s path goes under blocks in the manifest. Text outside the
markers is never touched.
uninstallBundle({dry}) removes each recorded file whose hash still matches (remove), leaves an
edited one (skip-edited), reports a missing one (gone), deletes an emptied skill folder, and
strips each recorded block. It saves the manifest, dropping removed entries.
init: put the bundle in place without configuring anything
init() in bin/ask-kit.mjs:
writeAgentsMd().detect({counts: false}).present= theTARGETSagents whose detection hasonPathtrue.installBundle(present, {force}).- Prints a line per agent with its file count, and the files it left alone.
- Prints “not found here” for every agent in
TARGETSthat is not inpresent, or whose base folder does not exist (theskip-no-agentrow).
It writes the bundle, installed.json and AGENTS.md. It does not write config.json and does
not register ask; that is setup or apply.
Why init and questions can disagree about an agent
Both start from the same field, onPath, which is the result of which(bin) followed by a
successful <bin> --version. They use it differently.
questionsshows it asinstalledinfound.agents.initalso needs the agent’s base folder (TARGETS[agent].base():~/.copilotorCOPILOT_HOMEfor Copilot). When it is missing,installBundlereturnsskip-no-agentandinitprints “not found here”, althoughinstalledis true.
A Copilot CLI that is on PATH but has no ~/.copilot folder yet (it has never been started, or
HOME or COPILOT_HOME points elsewhere) gives exactly this pair of messages. A shell function
wrapping command copilot does not matter to either check, because both look for an executable
file on PATH from Node, not in the shell. A --version that takes longer than 6 seconds on one
run would also make onPath false in one command and true in the other.
The message “not found here” does not say which of the two causes applies.
doctor
doctor() loads the config (it throws “not set up yet” without one), writes AGENTS.md, and prints:
- Node version and platform, ripgrep and git;
- for each source in
config.sources, the session count, ormissing (<where>); - for each backend: for an
apibackend, aGET <baseUrl>/modelswith the key (8-second timeout), reporting the HTTP status, an unknown model, orok; for Ollama the model’s context length against the context ask-kit asks for (contextTokens, default 32,768 insrc/ollama.mjs); for a CLI backend, “checked on first ask”; - the domain names and the router (
router.backend, or “keyword rules”).
It lists every key of config.domains, including those with enabled: false.
uninstall
uninstall() goes through config.clients, calls each REGISTER[client]().remove() (for Claude
Code claude mcp remove -s user ask; for Codex it strips the marked block; for JSON files it
deletes ask), then uninstallBundle(). With --dry-run it prints what it would do. The config,
keys and journals stay. Without a config file there is nothing in clients, so no registration is
removed.
The guide: src/agentsmd.mjs
agentsMd() builds a Markdown file with this machine’s real values: the command
(process.execPath plus bin/ask-kit.mjs), a “Now” section from config.json (sources,
clients, backends, domains, router; or “Not set up yet”), the file locations from config.mjs,
the domain folders from domainDirs(), the domains from listDomains(), and the task list an
agent matches a request against. writeAgentsMd() rewrites the file only when the text changed,
creates CONFIG_DIR with mode 0700, and never throws.
It runs in init, apply, doctor, ask-kit add and in serve, which means every time an agent
starts the MCP server. The skills and the rule point agents at this file through {{AGENTS_MD}}.
ask-kit report
report({since}) in src/report.mjs reads the journals under STATE_ROOT. The folder walk skips
warm, drafts, gallery and index. The first path segment is the domain name. since is
<n>h, <n>d or a date (default 7d).
- A line with
type: "ask"is an ask. Any other line with acodefield is a cell. - For cells it counts script runs per
<domain>/<script>(with(draft)for drafts, and failures whereokis false and the script was not just saved). A cell that ran no script is a hand-written cell;shapeOfblanks string and number literals,constnames and whitespace, keeps 90 characters, and counts equal shapes. - Each ask gets signals:
failed: <error>orcancelled;cut offorout of steps or time(partial);answered at the step limit(atLimit);slowover 90 s;costlyover $0.02;misstepsover 2;empty answer; andre-askedwhen the same session asks again within 3 minutes withoutcontinue(re-asked on another backendwhen the backend differs). - The result: totals,
medianSeconds,flaggedAsks,scriptsby runs, andworthAScript, the shapes written by hand three or more times (at most 10).
The journal fields it reads (ok, partial, cutAtLength, atLimit, ms, costUsd, missteps,
answerChars, session, continued, backend, question, cells or turns) are written by
registerAsk in src/ask.mjs through the keep callback in src/server.mjs. Renaming one
there changes the report. See the journal.
What to look at when changing it
- A new coding agent:
AGENTSand, if it can run the investigator,AGENT_CLISinsrc/providers.mjs;TARGETSinbundle.mjs;REGISTERinregister.mjs; an adapter insrc/transcripts/. See add an agent. - A new API preset:
API_PRESETSinproviders.mjs.detectandquestionspick it up from there. See add a backend. - A new question: add it to
questions(), handle the answer inplan(), document it in the header ofquestions.mjs, and update theask-kit-setupskill, which tells agents what the questions mean. - Anything that writes outside
CONFIG_DIRandSTATE_ROOTmust use the agent’s own environment variable, asTARGETSdoes, so tests can redirect it. - Tests.
test/setup.mjsgivesquestionsandplana made-up detection result. It asserts the question ids, the suggestions, that no key means a Codex subscription is suggested, that a missing key throws, that config never holds a key, thatkeys.envis mode 0600, and that applying twice leaves one[mcp_servers.ask]block and keeps the user’s other servers.test/bundle.mjsrunsinstallBundleagainst throwaway agent homes and asserts each action in the table above, the per-agent formats, an idempotent second run,skip-editedandskip-not-ours, block replacement,uninstallBundlekeeping edited files, and the guide containing the machine’s config path. Nothing testsdetect,init(),doctor(),report,register.mjsfor Claude Code, Gemini or opencode, orask-kit uninstall.
Things to watch for
applyrebuilds the config.plan()writes a new object from the answers. It does not merge with the existing file, so runningsetuporapplyagain dropsrouter.model, a domain’sbackend, thefromandcommitthatask-kit addrecorded, a backend’sbaseUrlorcontextTokens, and any domain not listed inanswers.domains. Thequestionsoutput includesexisting, so an agent can carry values over, but the code does not.- opencode is never registered by
setup.REGISTER.opencodeexists, butAGENTS.opencode.clientisnull, so theclientsquestion never offers it.initdoes install its bundle. - Gemini registration ignores
GEMINI_CLI_HOME, while the bundle and the transcript adapter honour it. render()andagentsMd()build the command differently.render()passesprocess.execPaththroughJSON.stringify(...).slice(1, -1), which doubles backslashes on Windows, and neither quotes a path with spaces.- The guide’s table is split. In
agentsMd()the line “Domains available now …” sits between table rows, so the “Journals” and “ask-kit itself” rows render as plain text.