Transcripts

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"
  • i is the event’s position in the session as the adapter emits it, counting from 0. It is the citation: cite() formats codex 5ca1ab1e #42. It is not a line number in the file.
  • user is what the person typed. system is context the agent injected (instruction files, reminders, environment blocks). The adapters decide which is which; that is the main difference between them.
  • tool_call and tool_result are paired by toolId. ok on a result is false when the agent reported a failure.
  • text is always a string. For a tool call it is the arguments as JSON text; input holds 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 } }.

  1. It reads the cache.
  2. For each file it calls statSync. When mtimeMs and size equal the cached values it reuses meta. Otherwise it calls readMeta(file), which reads the first 256 KB (head()).
  3. A file whose readMeta throws or returns null is cached as null and left out of the list, until the file changes.
  4. updatedAt is the file’s modification time.
  5. 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() is false;
  • 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 exec and copilot -p write like any other. A session is dropped when its cwd starts with STATE_ROOT or ends with /warm/cwd;
  • sorts newest first by updatedAt.

How history works

  • sessions(opts) filters by since and until (a number of hours ago, or a date), source (one or several), project (a substring of the project or the cwd) and cwd (a prefix). The result is cut to limit (default 50) with .total holding the count before the cut. since compares against updatedAt, until against startedAt.

  • session(ref) and the ref of events and usage accept an id, an id prefix or source: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 a RegExp. For each session in the window it first asks fileMayMatch(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 a RegExp (no words) or for an adapter with noPrefilter. Otherwise the adapter parses the file and each event of the wanted roles is tested. The default roles are user, assistant, tool_call and tool_result; system is 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_DIR replaces ~/.claude. available() is whether the projects folder 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.id and the same usage.
  • Files read: the .jsonl files directly in each project folder. files() does not go into <session>/subagents/.
  • Metadata (meta): from the first 256 KB, cwd and startedAt from the first lines that have them; title is a custom-title line if present, else the first summary line, 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 with isMeta set, becomes system; other user text becomes user; a tool_result block becomes tool_result with ok: !is_error. Assistant text blocks become assistant, tool_use blocks become tool_call with input. Thinking blocks and non-message lines are not read.
  • Usage: usage is summed per model, counting each message.id once (calls, input, cacheRead, cacheWrite, output).

Codex

  • Where: $CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl and $CODEX_HOME/archived_sessions/rollout-*.jsonl; CODEX_HOME defaults to ~/.codex. available() checks sessions/.
  • Format: JSONL of {timestamp, type, payload}. The types used are session_meta, turn_context (gives the model), response_item and event_msg.
  • Metadata: id, cwd and the start time from session_meta; the title is the first user message that does not start with a tag in INJECTED (# AGENTS.md instructions, <environment_context> and others). originator is also kept.
  • Events: only response_item lines. A message is assistant, user (when not injected) or system. function_call, custom_tool_call, local_shell_call and web_search_call become tool_call; their text is the arguments string and input is not set. Their outputs (function_call_output, custom_tool_call_output) become tool_result. ok is the output’s success when present, otherwise a guess: the first 200 characters must not start a line with Exit code: 1-9 or error. A web_search_call has no toolId, so it has no paired result.
  • Usage: the last token_count event holds the running total. input is input_tokens - cached_input_tokens; reasoning is added to the usual fields.

GitHub Copilot CLI

  • Where: ~/.copilot/session-state/<session id>/events.jsonl; COPILOT_HOME replaces ~/.copilot. available() checks session-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, startTime and selectedModel from session.start; the title is the first user.message. A file with no session.start line in its first 256 KB is skipped.
  • Events: user.message is user, with no system filtering (Copilot does not store injected context as messages). An assistant.message with empty content is skipped. Tool start and complete events become tool_call (with input) and tool_result (ok: success !== false).
  • Usage: each session.usage_record is one call; premiumRequests is the sum of its cost.

Gemini CLI

  • Where: ~/.gemini/tmp/<project hash>/chats/session-*.json; GEMINI_CLI_HOME replaces ~/.gemini. The adapter searches up to three folder levels under tmp, and available() is true when at least one such file exists.
  • Format: one JSON document per session: {sessionId, projectHash, startTime, messages: [...]} with messages of type user, gemini, info or error, and toolCalls inside gemini messages.
  • Metadata: there is no working directory in the file, so cwd is null and project is gemini: plus the first 8 characters of the hash. The project filter of history therefore matches that string. The investigator-session filter, which looks at cwd, never applies.
  • Events: user is user; gemini gives assistant text, then each tool call and its result (ok: status !== "error"); info and error are system.
  • 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_DB replaces the file, and XDG_DATA_HOME replaces ~/.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_v2 holds sessions (directory, title, times in milliseconds, token totals, cost, model as JSON); sessions with time_archived set are left out. session_message holds messages (type, seq, data as JSON).
  • Events: a user message gives user from data.text or data.content. For an assistant message each content part is tested in turn: reasoning is skipped; a part with tool, callID or type tool gives a tool_call and, when it has output, a tool_result; a part with text gives assistant.
  • Usage: the totals on the session_v2 row, as one entry keyed by the model id, with costUsd.
  • 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:machine on 18 November 2026 against a real opencode 2.3.2 database with three sessions read them and found user and assistant events, and usage returned the model as unknown on 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) and events (the whole file, not cached). A change to meta needs the cache cleared to be seen on files already indexed, because the cache key is only the file’s mtimeMs and size. Delete STATE_ROOT/index/<source>.json.
  • Role decisions change answers. Moving text between user and system, or dropping an event, changes what grep finds by default and what session-digest reports as the person’s prompts.
  • Keep domains/sessions/api.d.ts and domains/sessions/instructions.md in step: the instructions name each agent’s tool names and the cite format.
  • fileMayMatch assumes 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. Set noPrefilter: true on an adapter that cannot make that promise.
  • Adapters do not catch errors in events(). A JSONL file with a broken line is fine (parseLines skips it), but a Gemini file that is not valid JSON makes read() throw inside grep, which ends that search.
  • Adding an agent touches more than the adapter: ADAPTERS in index.mjs, the Source type in api.d.ts, AGENTS in src/providers.mjs, TARGETS in src/setup/bundle.mjs, REGISTER in src/setup/register.mjs, and a fixture. See add an agent.
  • Tests: test/fixtures.mjs copies test/fixtures/ into a temporary folder, points CLAUDE_CONFIG_DIR, CODEX_HOME, COPILOT_HOME, GEMINI_CLI_HOME, OPENCODE_DB and ASK_KIT_STATE there, and only then imports the adapters (they read the environment when called, but STATE_ROOT is read at import). It checks, per agent, the session id, cwd, project, title, the exact role sequence, the ok of paired results, and usage; and through makeHistory it checks the investigator-session exclusion, filters, word and RegExp search, role defaults and id-prefix lookup. Test data uses names from the Discworld (see CONTRIBUTING.md); never put a real transcript in test/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.