ask-kit records every ask and every REPL cell. The records are plain JSON lines you can read with
jq, and ask-kit report summarises them. This page describes the files, the fields and how the
report uses them.
Sources:
src/server.mjs (journal,
runCell, keep),
src/ask.mjs (the result objects of
askClaude, askCodex, askCopilot, askApi),
src/router.mjs (journal) and
src/report.mjs (report).
Files
A journal file is <state>/<session>.jsonl, with one JSON object per line. <state> is the
domain’s folder in the state folder; see Files and environment variables.
Files are created with mode 0600 and only ever appended to.
| File | Written by | Holds |
|---|---|---|
<state>/<caller session>.jsonl |
The server the calling agent talks to | One ask record per ask from that session. |
<state>/<investigator session>.jsonl |
The investigator’s REPL server | One cell record per cell the investigator ran. For api and Copilot CLI asks the session is ask-<uuid>. |
<STATE_ROOT>/router/<caller session>.jsonl |
The router | One routing record per routed ask. |
Nothing rotates or deletes a journal. To see which journal a record is in, look at the journal
field of ask-kit report --json.
A line that is not valid JSON is skipped by the report.
Ask record
Written once per ask, whether it succeeded or not. type is "ask".
| Field | Type | Meaning |
|---|---|---|
ts |
string | ISO time the record was written (the end of the ask). |
session |
string | The calling session. |
type |
"ask" |
Marks the record. |
question |
string | The question, in full. |
backend |
string | The backend’s name. |
kind |
string | api, claude-cli, codex-cli or copilot-cli. |
ok |
boolean | false when the ask failed. |
continued |
boolean | A follow-up. |
ms |
number | Duration of the ask. For the CLIs that warm a session it leaves out the warm-up. |
answerChars |
number | Length of the answer text. The answer itself is not stored. |
error |
string | On failure: the message, cut at 300 characters. |
cancelled |
boolean | On failure: the calling client cancelled the ask. |
The rest depend on the kind. A field that a kind does not produce is absent.
| Field | Kinds | Meaning |
|---|---|---|
model |
all | The model. codex default or copilot default when none was set. |
costUsd |
all | Dollars, or null when the provider does not report a cost. Reported for OpenRouter and claude-cli. For claude-cli it is this ask’s share, with the warm-up taken out. |
usage |
all | { input, cacheRead, output }, and cacheWrite for api and claude-cli. Tokens. |
turns |
api, claude-cli |
Model calls in the ask. |
cells |
api, codex-cli, copilot-cli |
REPL cells run (tool calls, for Copilot). |
warm |
claude-cli, codex-cli |
{ reused }, and warmCostUsd for claude-cli: whether the warm session was reused, and what a fresh warm-up cost. |
partial |
api |
The ask ran out of steps or time, or was cut at the length limit. |
cutAtLength |
api |
A reply hit the length limit. |
atLimit |
api |
The answer came with two or fewer steps left. |
providers |
api |
The providers that served the calls, where the API says (OpenRouter does). |
missteps |
api |
Replies that were empty or held tool-call markup instead of a tool call. |
premiumRequests |
copilot-cli |
Premium requests used. |
Cell record
Written after every REPL cell. It has code and no type.
| Field | Type | Meaning |
|---|---|---|
ts |
string | ISO time the cell ended. |
session |
string | The investigator’s session. |
ok |
boolean | false when the cell threw or timed out. |
ms |
number | Duration. |
code |
string | The cell’s code, as sent. |
declared |
string[] | Names the cell declared at its top level. |
resultChars |
number | Length of the text returned, after clipping. |
repeat |
number | Present when this cell, with its variable names blanked, has run before in this REPL: how many times now. |
error |
string or null |
The error’s first lines. |
scripts |
object[] | Scripts the cell ran: { name, draft, ok, ms }, plus error on failure. A draft saved with scripts.draft appears as { name, draft: true, saved: true }. |
calls |
object[] | Calls the domain’s globals made: { kind, detail, ms, size }. For repo: rg, files, read, git. For history: sessions, events, grep. size is the number of results or lines. |
snapshot |
object | { vars, fns, bytes, dropped } after the cell, or { error }. dropped names variables that could not be saved. |
restored |
object or null |
On the first cell after a start: { from, savedAt, names }, the variables brought back. |
A cell record, trimmed:
{"ts":"2026-11-18T09:29:08.474Z","session":"ask-3f1c…","ok":true,"ms":2,
"code":"const r = await scripts.run(\"find-notes\", { topic: \"action items\" }); r",
"declared":["r"],"resultChars":318,"error":null,
"scripts":[{"name":"find-notes","draft":false,"ok":true,"ms":1}],
"calls":[{"kind":"list","detail":"{\"max\":10000}","ms":0,"size":2},
{"kind":"search","detail":"action items","ms":0,"size":2}],
"snapshot":{"vars":1,"fns":0,"bytes":220,"dropped":[]},"restored":null}
Routing record
Written by the router before it forwards a call.
| Field | Meaning |
|---|---|
at |
ISO time. |
question |
The question, cut at 500 characters. |
domain |
The domain chosen. |
how |
caller, follow-up, only, model or rules. See The ask tool. |
routeMs |
Time the choice took. |
routeError |
When the router model failed and the keyword rules decided: why, cut at 160 characters. |
The report ignores routing records.
ask-kit report
ask-kit report [--since 7d] [--json]
--since takes <n>h, <n>d or a date. The default is 7d. Any other value stops with
--since <value>: use 24h, 7d or a date. The command reads every journal in the state folder
(folders warm, drafts, gallery and index are skipped), keeps records whose ts is in
range, and builds three things.
Flagged asks
Each ask record gets zero or more signals. An ask with any signal is listed.
| Signal | When |
|---|---|
failed: <error> |
ok is false. |
cancelled |
ok is false and cancelled is true. |
out of steps or time |
partial is true. |
cut off |
partial is true because of cutAtLength. |
answered at the step limit |
atLimit is true. |
slow (<n>s) |
ms over 90 000. |
costly ($<n>) |
costUsd over 0.02. |
<n> missteps |
missteps over 2. |
empty answer |
ok is true and answerChars is 0. |
re-asked |
The same calling session asked again within three minutes, and not as a follow-up. A sign the first answer fell short. |
re-asked on another backend |
Same, and the second ask used a different backend. |
Scripts
For every cell record with a scripts list, one count per script, keyed <domain>/<name> with
(draft) added for drafts: runs, and failed (runs where ok is false and the record is not a
save).
Routes worth a script
For every cell that ran no script, the report takes the cell’s shape: the code with strings
replaced by "…", numbers by N, const x = removed, whitespace collapsed, cut at 90
characters. The key is <domain>: <shape>. A shape written three or more times is listed,
largest first, at most ten. Each is a search the investigator keeps writing by hand and could be a
script.
Output
Text:
Since 2026-11-11T09:27:08.327Z: 12 asks, 2 flagged, $0.0341, median 18 s
<ts> <domain> · <backend> · <seconds>s <signals joined by "; ">
<question, cut at 140 characters>
<journal file>
Scripts: code/where 9, sessions/grep 4 (1 failed)
Written by hand 3+ times (worth a script):
4× <shape>
--json prints:
| Field | Meaning |
|---|---|
since |
ISO time the range starts. |
asks |
Asks in range. |
flagged |
Asks with a signal. |
costUsd |
Sum of costUsd. |
medianSeconds |
Median duration in seconds, or null with no asks. |
flaggedAsks |
[{ ts, domain, backend, session, question, ms, costUsd, cells, signals, journal }]. cells is cells or else turns. |
scripts |
[{ name, runs, failed }], most used first. |
worthAScript |
[{ shape, n }]. |
The domain in the report is the first path part under the state folder. For the code domain it
is code for every repository.
To read one flagged ask, open the journal named in journal, find the ask by question, and read
the cell records of its investigator. Find and fix a bad answer
walks through it.
Related: Make it better, Files and environment variables.