src/transcripts/ reads the transcripts that coding agents already write and turns each agent’s
format into one shape. The sessions domain gets the result as the history global. There is no
proxy and no database of ask-kit’s own, except a small cache of session metadata.
Files
| File | What is in it |
|---|---|
| src/transcripts/index.mjs | ADAPTERS (the five adapters by name), makeHistory({sources, push}) (the history API: sources, sessions, session, events, usage, grep), cite. |
| src/transcripts/common.mjs | The event shape (header comment), indexed (the cache), fileMayMatch (the search pre-filter), head, parseLines, walk, textOf, titleOf, clip. |
| src/transcripts/claude-code.mjs | adapter for Claude Code. |
| src/transcripts/codex.mjs | adapter for Codex. |
| src/transcripts/copilot-cli.mjs | adapter for GitHub Copilot CLI. |
| src/transcripts/gemini-cli.mjs | adapter for Gemini CLI. |
| src/transcripts/opencode.mjs | adapter for opencode. |
| domains/sessions/api.d.ts | The types the investigator reads: Session, Event, Hit, Window, history, cite. Keep it in step with the adapters. |
| test/fixtures.mjs | Tests for every adapter and for makeHistory. |
| test/fixtures/ | The made-up stores the test copies into a temporary folder. |
| test/adapters.mjs | The same adapters against this machine’s real transcripts (npm run test:machine). |
The adapter contract
Each adapter module exports adapter, an object with:
| Member | Meaning |
|---|---|
name, label |
The source id (claude-code, codex, copilot-cli, gemini-cli, opencode) and a display name. |
where() |
The folder or file the adapter reads. Shown in detect, doctor and history.sources(). |
available() |
Whether the store exists on this machine. |
sessions() |
The sessions, as {source, file, size, updatedAt, id, cwd, project, startedAt, title, ...}. File-based adapters build it with indexed(). |
events(session) |
The normalised events of one session. |
usage(session) |
Token counts by model. |
noPrefilter |
Optional. true when fileMayMatch cannot be used on the store (opencode). |
All paths come from os.homedir() and environment overrides. No adapter branches on the
operating system, so each store is read from the same place relative to the home folder on
Linux, macOS and Windows (%USERPROFILE% on Windows).
The event shape
common.mjs documents it at the top:
// { i, ts, role, text, tool?, toolId?, input?, ok?, model? }
// role: "user" | "assistant" | "tool_call" | "tool_result" | "system"
iis the event’s position in the session as the adapter emits it, counting from 0. It is the citation:cite()formatscodex 5ca1ab1e #42. It is not a line number in the file.useris what the person typed.systemis context the agent injected (instruction files, reminders, environment blocks). The adapters decide which is which; that is the main difference between them.tool_callandtool_resultare paired bytoolId.okon a result isfalsewhen the agent reported a failure.textis always a string. For a tool call it is the arguments as JSON text;inputholds the parsed arguments where the agent stores them parsed (Claude Code, Copilot, Gemini).
A session record has source, id, cwd, project (the base name of cwd), title (a
summary or the first typed prompt, clipped to 120 characters), startedAt and updatedAt.
makeHistory removes file and size from what the REPL sees and adds kb.
The session index
Reading the first part of thousands of files on every question would be slow, so
indexed(source, files, readMeta) keeps the metadata. The cache is one file per source,
STATE_ROOT/index/<source>.json, shaped { "<file path>": { mtimeMs, size, meta } }.
- It reads the cache.
- For each file it calls
statSync. WhenmtimeMsandsizeequal the cached values it reusesmeta. Otherwise it callsreadMeta(file), which reads the first 256 KB (head()). - A file whose
readMetathrows or returnsnullis cached asnulland left out of the list, until the file changes. updatedAtis the file’s modification time.- If anything changed, or the number of entries differs (a file was deleted), the cache is written to a temporary file and renamed. Write errors are ignored.
Deleting STATE_ROOT/index/ is safe; it is rebuilt. ask-kit detect, questions and doctor
all call sessions(), so they write this cache too.
makeHistory adds an in-process cache of the whole session list for 30 seconds (all()).
all() also:
- skips an adapter whose
available()isfalse; - turns an adapter error into an
{source, error}entry and then drops it, so a failing adapter looks like a source with no sessions; - drops ask-kit’s own investigator sessions, which
claude -p,codex execandcopilot -pwrite like any other. A session is dropped when itscwdstarts withSTATE_ROOTor ends with/warm/cwd; - sorts newest first by
updatedAt.
How history works
-
sessions(opts)filters bysinceanduntil(a number of hours ago, or a date),source(one or several),project(a substring of the project or thecwd) andcwd(a prefix). The result is cut tolimit(default 50) with.totalholding the count before the cut.sincecompares againstupdatedAt,untilagainststartedAt. -
session(ref)and therefofeventsandusageaccept an id, an id prefix orsource:id. A prefix matching several sessions throws, unless one of them equals it exactly. -
events(ref, {roles, from, to, maxText})calls the adapter, which parses the whole file again on every call, then filters. -
grep(query, opts)takes words (all must appear in one event, any case) or aRegExp. For each session in the window it first asksfileMayMatch(file, words). That check lower-cases the file and looks for one raw line that holds every word, in its JSON-escaped form, without parsing. A file that fails is skipped. It is not used for aRegExp(no words) or for an adapter withnoPrefilter. Otherwise the adapter parses the file and each event of the wanted roles is tested. The default roles areuser,assistant,tool_callandtool_result;systemis searched only when asked for.The result array has
total(all matches),complete(total <= max, default 100),scanned(files parsed) and, when the 40-second budget ran out,stoppedEarly. The budget is checked after each session, newest first, so a long search loses the oldest sessions.
Claude Code
- Where:
~/.claude/projects/<encoded cwd>/<session id>.jsonl.CLAUDE_CONFIG_DIRreplaces~/.claude.available()is whether theprojectsfolder exists. - Format: JSONL. Each line is one message part. An assistant message is split into one line
per content block, all with the same
message.idand the sameusage. - Files read: the
.jsonlfiles directly in each project folder.files()does not go into<session>/subagents/. - Metadata (
meta): from the first 256 KB,cwdandstartedAtfrom the first lines that have them;titleis acustom-titleline if present, else the firstsummaryline, else the first user prompt that is not injected. A file with no timestamp in that range is skipped. - Events: a user line whose text starts with one of the tags in
INJECTED(<command-name>,<system-reminder>,<local-command-stdout>and others), or withisMetaset, becomessystem; other user text becomesuser; atool_resultblock becomestool_resultwithok: !is_error. Assistanttextblocks becomeassistant,tool_useblocks becometool_callwithinput. Thinking blocks and non-message lines are not read. - Usage:
usageis summed per model, counting eachmessage.idonce (calls,input,cacheRead,cacheWrite,output).
Codex
- Where:
$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonland$CODEX_HOME/archived_sessions/rollout-*.jsonl;CODEX_HOMEdefaults to~/.codex.available()checkssessions/. - Format: JSONL of
{timestamp, type, payload}. The types used aresession_meta,turn_context(gives the model),response_itemandevent_msg. - Metadata:
id,cwdand the start time fromsession_meta; the title is the first user message that does not start with a tag inINJECTED(# AGENTS.md instructions,<environment_context>and others).originatoris also kept. - Events: only
response_itemlines. Amessageisassistant,user(when not injected) orsystem.function_call,custom_tool_call,local_shell_callandweb_search_callbecometool_call; theirtextis the arguments string andinputis not set. Their outputs (function_call_output,custom_tool_call_output) becometool_result.okis the output’ssuccesswhen present, otherwise a guess: the first 200 characters must not start a line withExit code: 1-9orerror. Aweb_search_callhas notoolId, so it has no paired result. - Usage: the last
token_countevent holds the running total.inputisinput_tokens - cached_input_tokens;reasoningis added to the usual fields.
GitHub Copilot CLI
- Where:
~/.copilot/session-state/<session id>/events.jsonl;COPILOT_HOMEreplaces~/.copilot.available()checkssession-state/. - Format: JSONL of
{type, data, id, timestamp}:session.start,user.message,assistant.message,tool.execution_start,tool.execution_complete,session.usage_record. - Metadata:
sessionId,context.cwd,startTimeandselectedModelfromsession.start; the title is the firstuser.message. A file with nosession.startline in its first 256 KB is skipped. - Events:
user.messageisuser, with nosystemfiltering (Copilot does not store injected context as messages). Anassistant.messagewith empty content is skipped. Tool start and complete events becometool_call(withinput) andtool_result(ok: success !== false). - Usage: each
session.usage_recordis one call;premiumRequestsis the sum of itscost.
Gemini CLI
- Where:
~/.gemini/tmp/<project hash>/chats/session-*.json;GEMINI_CLI_HOMEreplaces~/.gemini. The adapter searches up to three folder levels undertmp, andavailable()is true when at least one such file exists. - Format: one JSON document per session:
{sessionId, projectHash, startTime, messages: [...]}with messages of typeuser,gemini,infoorerror, andtoolCallsinsidegeminimessages. - Metadata: there is no working directory in the file, so
cwdisnullandprojectisgemini:plus the first 8 characters of the hash. Theprojectfilter ofhistorytherefore matches that string. The investigator-session filter, which looks atcwd, never applies. - Events:
userisuser;geminigivesassistanttext, then each tool call and its result (ok: status !== "error");infoanderroraresystem. - Usage: from each message’s
tokens(input,cached,output). - Status: the header comment says it is “not yet checked against a real store”, so every field is read defensively. It is covered by a made-up fixture only, and the format has not been confirmed on a real install.
opencode
- Where: one SQLite file,
~/.local/share/opencode/opencode.db.OPENCODE_DBreplaces the file, andXDG_DATA_HOMEreplaces~/.local/share. The adapter has no Windows-specific path. - Format: read-only through
node:sqlite(the reason ask-kit needs Node 22.13 or newer).session_v2holds sessions (directory,title, times in milliseconds, token totals,cost,modelas JSON); sessions withtime_archivedset are left out.session_messageholds messages (type,seq,dataas JSON). - Events: a
usermessage givesuserfromdata.textordata.content. For anassistantmessage each content part is tested in turn:reasoningis skipped; a part withtool,callIDor typetoolgives atool_calland, when it has output, atool_result; a part withtextgivesassistant. - Usage: the totals on the
session_v2row, as one entry keyed by the model id, withcostUsd. - Search:
noPrefilter: true. There are no files to scan, so a search reads the messages of every session in the window. - Status: the tests build a database with only the columns the adapter reads. A run of
npm run test:machineon 18 November 2026 against a real opencode 2.3.2 database with three sessions read them and found user and assistant events, andusagereturned the model asunknownon the session it checked. Tool calls and results on a real database have not been checked.
What to look at when changing it
- A transcript is read in two places:
meta(first 256 KB, cached) andevents(the whole file, not cached). A change tometaneeds the cache cleared to be seen on files already indexed, because the cache key is only the file’smtimeMsandsize. DeleteSTATE_ROOT/index/<source>.json. - Role decisions change answers. Moving text between
userandsystem, or dropping an event, changes whatgrepfinds by default and whatsession-digestreports as the person’s prompts. - Keep
domains/sessions/api.d.tsanddomains/sessions/instructions.mdin step: the instructions name each agent’s tool names and the cite format. fileMayMatchassumes one event sits on one line of the file. That holds for JSONL. For a document that spans several lines (Gemini, if its files are pretty-printed) a multi-word search can skip a file that holds the event. SetnoPrefilter: trueon an adapter that cannot make that promise.- Adapters do not catch errors in
events(). A JSONL file with a broken line is fine (parseLinesskips it), but a Gemini file that is not valid JSON makesread()throw insidegrep, which ends that search. - Adding an agent touches more than the adapter:
ADAPTERSinindex.mjs, theSourcetype inapi.d.ts,AGENTSinsrc/providers.mjs,TARGETSinsrc/setup/bundle.mjs,REGISTERinsrc/setup/register.mjs, and a fixture. See add an agent. - Tests:
test/fixtures.mjscopiestest/fixtures/into a temporary folder, pointsCLAUDE_CONFIG_DIR,CODEX_HOME,COPILOT_HOME,GEMINI_CLI_HOME,OPENCODE_DBandASK_KIT_STATEthere, and only then imports the adapters (they read the environment when called, butSTATE_ROOTis read at import). It checks, per agent, the session id,cwd,project,title, the exact role sequence, theokof paired results, andusage; and throughmakeHistoryit checks the investigator-session exclusion, filters, word andRegExpsearch, role defaults and id-prefix lookup. Test data uses names from the Discworld (seeCONTRIBUTING.md); never put a real transcript intest/fixtures/. npm run test:machine(test/adapters.mjs) asserts that every available real store yields sessions and a user event. It prints session titles, so do not paste its output into an issue.