Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* Reading one past Claude Code transcript for `trail init`'s look-back: what
* the person typed (g4's shared filter decides, so IDE tags and reminders are
* stripped and the prompt kept, pastes become a marker), each with its own
* time and the end of Claude's reply before it, plus the tool calls, so a
* session started in a folder above the repo can be judged by how much of its
* work was in the repo.
*
* Files are read in chunks, line by line, never whole: one real transcript
* passed 233 MB. Tool results are never parsed (they are most of the bytes
* and hold nothing the person typed), and neither is any line over 2 MB.
*/
import { closeSync, readSync } from "node:fs";
import { basename } from "node:path";
import { openPlain } from "./plain-file.js";
import { ownText, textOf, typedText } from "../trace/claude.js";
import { labInteractive } from "../skills/host-facts.js";
/** Where a past session was found, as `trail init` counts them. */
export type SessionSource = "own" | "worktree" | "clone" | "ancestor";
/** One message the person wrote, with the end of what Claude said just before it. */
export interface PastPrompt {
text: string;
/** The tail of Claude's last reply before this message, so "no, use a worktree" reads on its own. */
before?: string;
/** ISO time it was sent, when the transcript says. */
at?: string;
}
export interface PastSession {
id: string;
/** ISO time of the first message. */
at: string;
branch?: string;
prompts: PastPrompt[];
source?: SessionSource;
/** The transcript file. */
path?: string;
/** The byte range the repo's work is in: the whole file, or an ancestor session's in-repo stretch (design 4.1). */
stretch?: { from: number; to: number };
}
const PROMPT_CHARS = 1200;
const BEFORE_CHARS = 240;
/** How much of a file's start is read to find where its session began. */
const HEAD_BYTES = 256 * 1024;
const CHUNK_BYTES = 4 * 1024 * 1024;
/** No typed message or tool call worth reading is this long: a line over it is skipped unparsed. */
const MAX_LINE = 2 * 1024 * 1024;
const NEWLINE = 0x0a;
/**
* The date an ISO time fell on where the person lives (this machine's time
* zone), `2026-10-09`; "" for anything else. Not the UTC date: UTC midnight
* is mid-afternoon in California, so a restart at 4:55 and 5:05 pm would
* count as two days.
*/
export function dayOf(iso: string | undefined): string {
if (!iso || !/^\d{4}-\d{2}-\d{2}/.test(iso)) return "";
if (!/T\d{2}:\d{2}/.test(iso)) return iso.slice(0, 10);
const d = new Date(iso);
if (Number.isNaN(d.getTime())) return "";
const two = (n: number) => String(n).padStart(2, "0");
return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;
}
/**
* Each complete line of `path`, in order, read in chunks, with the byte offset it starts at. `range` reads only
* the lines that start at or after `from` and before `to` (`from` must be a line start). Lines over 2 MB are
* skipped unread. Throws when the file can't be opened or isn't a plain file (a FIFO would hang the read).
*/
export function eachLine(path: string, onLine: (line: string, offset: number) => void, range?: { from: number; to: number }): void {
// Never a FIFO or a device, even one swapped in after discovery's stat (b5 review).
const fd = openPlain(path, { follow: true });
try {
const buf = Buffer.allocUnsafe(CHUNK_BYTES);
const end = range ? Math.max(0, range.to) : Infinity;
let pos = range ? Math.max(0, range.from) : 0;
let carry: Buffer = Buffer.alloc(0);
// A line longer than MAX_LINE is dropped as it streams by, never held whole.
let skipping = false;
// Past `to`, read on only to finish a line that started before it.
while (pos < end || (!skipping && carry.length > 0 && pos - carry.length < end)) {
const got = readSync(fd, buf, 0, CHUNK_BYTES, pos);
if (got <= 0) break;
const dataStart = pos - carry.length;
pos += got;
const data = carry.length ? Buffer.concat([carry, buf.subarray(0, got)]) : buf.subarray(0, got);
let from = 0;
for (let nl = data.indexOf(NEWLINE, from); nl !== -1; nl = data.indexOf(NEWLINE, from)) {
const at = dataStart + from;
if (at >= end) return;
if (!skipping && nl > from && nl - from <= MAX_LINE) onLine(data.toString("utf8", from, nl), at);
skipping = false;
from = nl + 1;
}
if (data.length - from > MAX_LINE) {
skipping = true;
carry = Buffer.alloc(0);
} else carry = Buffer.from(data.subarray(from));
}
const at = pos - carry.length;
if (!skipping && carry.length && carry.length <= MAX_LINE && at < end) onLine(carry.toString("utf8"), at);
} finally {
closeSync(fd);
}
}
/** The first `cwd` in the first 256 KB of a transcript: the folder its session started in. Null when there's none or the file can't be read. */
export function firstCwd(path: string): string | null {
let text: string;
try {
const fd = openPlain(path, { follow: true });
try {
const buf = Buffer.allocUnsafe(HEAD_BYTES);
text = buf.toString("utf8", 0, readSync(fd, buf, 0, HEAD_BYTES, 0));
} finally {
closeSync(fd);
}
} catch {
return null;
}
const m = /"cwd":"((?:[^"\\]|\\.)*)"/.exec(text);
if (!m) return null;
try {
return JSON.parse(`"${m[1]}"`) as string;
} catch {
return null;
}
}
/** One message's words, cut at PROMPT_CHARS; null when there are none. */
function capped(t: string): string | null {
if (!t) return null;
return t.length > PROMPT_CHARS ? `${t.slice(0, PROMPT_CHARS)}…` : t;
}
/** The person's message with what isn't theirs taken out (trace/claude.ts decides), or null when nothing of theirs is left. */
export function ownWords(raw: string): string | null {
return capped(ownText(raw));
}
interface Entry {
type?: string;
cwd?: string;
entrypoint?: string;
timestamp?: string;
gitBranch?: string;
isSidechain?: boolean;
message?: { content?: unknown } | null;
}
/** Everything the look-back takes from one transcript, in the order it happened. */
export interface Scan {
/** A headless run (`claude -p`, the SDKs): its prompts were written once and replayed. */
headless: boolean;
branch?: string;
/** The person's messages; `i` is the order among prompts and calls, `o` the byte offset of its line. */
prompts: (PastPrompt & { i: number; o: number })[];
/** Tool calls; `inRepo` only when a `touches` test was given; `o` the byte offset of its line. */
calls: { i: number; o: number; inRepo: boolean }[];
}
/**
* One transcript's typed messages and tool calls. `touches(cwd, name, input)`
* says whether a tool call worked in the repo; without it every call counts
* as out of the repo. `env` decides only whether an sdk run is read (a lab home with the switch, D99). Never throws:
* an unreadable file scans as empty.
*/
export function scanTranscript(path: string, touches?: (cwd: string, name: string, input: unknown) => boolean,
env: NodeJS.ProcessEnv = process.env): Scan {
const scan: Scan = { headless: false, prompts: [], calls: [] };
let i = 0;
let lastReply = "";
try {
eachLine(path, (line, o) => {
// Tool output is most of a transcript and never the person's words.
if (scan.headless || line.includes('"type":"tool_result"')) return;
let e: Entry;
try {
e = JSON.parse(line) as Entry;
} catch {
return;
}
if (!e || typeof e !== "object") return;
// A script's run, unless a lab home has the switch (D99, D136 (2)), as the hooks read it.
if (typeof e.entrypoint === "string" && e.entrypoint.startsWith("sdk") && !labInteractive(env)) {
scan.headless = true;
return;
}
if (e.isSidechain) return;
if (e.type === "assistant") {
const content = e.message?.content;
const said = textOf(content).trim();
if (said) lastReply = said;
if (!Array.isArray(content)) return;
for (const part of content as Array<Record<string, unknown> | null>) {
if (!part || typeof part !== "object" || part.type !== "tool_use") continue;
let inRepo = false;
try {
inRepo = touches ? touches(typeof e.cwd === "string" ? e.cwd : "", String(part.name ?? ""), part.input) : false;
} catch {
/* a call that can't be judged isn't in the repo */
}
scan.calls.push({ i: i++, o, inRepo });
}
return;
}
// The one typed-words filter every learning path shares.
const words = capped(typedText(e, env));
if (!words) return;
scan.branch ||= e.gitBranch;
const before = lastReply ? lastReply.slice(-BEFORE_CHARS).replace(/\s+/g, " ").trim() : undefined;
const at = typeof e.timestamp === "string" ? e.timestamp : undefined;
scan.prompts.push({ text: words, ...(before ? { before } : {}), ...(at ? { at } : {}), i: i++, o });
lastReply = "";
});
} catch {
/* unreadable: nothing in it */
}
return scan;
}
/** A session from scanned prompts, or null when none is left. */
export function sessionOf(path: string, scan: Scan, prompts: Array<PastPrompt & { i: number; o?: number }> = scan.prompts, source?: SessionSource): PastSession | null {
if (scan.headless || !prompts.length) return null;
return {
id: basename(path, ".jsonl"),
path,
at: prompts.find((p) => p.at)?.at ?? "",
branch: scan.branch,
prompts: prompts.map(({ i: _i, o: _o, ...p }) => p),
...(source ? { source } : {}),
};
}
/**
* One transcript's messages from the person, oldest first. Headless runs
* (`claude -p`, scripts) are skipped whole: their prompts were written once
* and replayed, so a repeat there isn't the person repeating themselves.
*/
export function readSession(path: string): PastSession | null {
return sessionOf(path, scanTranscript(path));
}