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
/**
* When the Stop hook asks for a learning: on a sign in the transcript that the
* session found something the code won't tell the next person, not on a count
* of tool calls. A count fired on the first busy turn of a session, which is
* usually setting things up, and the learnings it got were about that.
*
* The signs, best first:
* - `fixed`: a test or build command failed, then passed after an edit;
* - `corrected`: the person corrected the agent ("no, …", "we use …"), and the
* agent went on to change code;
* - `undone`: an edit was undone (`git restore`, `git revert`, …);
* - `chose`: the person picked one of the options the agent offered, and the
* agent went on to change code;
* - `shipped`: `git commit`, `git push` or `gh pr create` after code edits;
* - `explored`: one turn took NOTE_WORTHY_READING tokens of reading to answer,
* with no edit needed: where a feature lives, why a bug happens.
*
* Only what happened since the session's last saved learning counts, so each
* learning starts the count over. Work on trail's own files (`.trail/`,
* `.claude/`, AGENTS.md …) is never a sign: that's setup, not the repo's code.
*
* Pure, for tests: `noteSignals` takes the transcript's JSONL.
*/
import { existsSync } from 'node:fs';
import { isAbsolute, relative, resolve, sep } from 'node:path';
import { trailOwnPath } from '../notes/git-facts.js';
import { NOTE_CALL } from '../notes/session-cost.js';
export type NoteSignalKind = 'fixed' | 'corrected' | 'undone' | 'chose' | 'shipped' | 'explored';
export interface NoteSignal {
kind: NoteSignalKind;
/** What raised it (its transcript entry), so one sign is asked about once. */
key: string;
/** What happened, in the session's own terms: the first line of the ask. */
what: string;
}
/** Most times the Stop hook asks for a learning in one session. */
export const NOTE_ASKS_PER_SESSION = 3;
/**
* Reading in one turn, in tokens, before it counts as digging worth a learning:
* what trail's answers stood in for, plus the repo files and search results the
* agent read itself. trail answers most questions in one or two calls, so
* finding where something lives never needed an edit to be worth saving.
*/
export const NOTE_WORTHY_READING = 30_000;
/** The reading a trail answer stood in for, from its `[trail] tokens saved ≈ N` line. A reused learning's own line doesn't count: that digging was done before. */
const TRAIL_SAVED = /\[(?:graft|trail)\] tokens saved ≈ ([\d,]+)/g;
/** Claude Code's tools that read the repo. */
const READ_TOOLS = new Set(['Read', 'Grep', 'Glob']);
/** Claude Code's tools that change a file. */
const EDIT_TOOLS = new Set(['Edit', 'MultiEdit', 'Write', 'NotebookEdit']);
/**
* A shell command that writes files: an in-place `sed`/`perl`, a redirect or
* `tee` into a file, a patch, or a script that opens one for writing. Agents
* often edit this way (a `python3 - <<EOF` that rewrites a file), and a fix
* made so is still a fix.
*/
const BASH_WRITE =
/\bsed\s+(?:-[a-zA-Z]+\s+)*-i|\bperl\s+-[a-z]*i|\btee\s|(?:^|[^>&0-9])>>?\s*[\w./~-]+\.\w+|\bgit\s+apply\b|\bapply_patch\b|\bopen\([^)]*,\s*['"][wa]|\.write_text\(|\bwriteFileSync\(/m;
const CODE_EXT = '(?:go|tsx?|jsx?|mjs|cjs|py|rb|rs|java|kt|swift|cs|php|c|h|cc|cpp|hpp|scala|sql|ya?ml|json|toml|sh|css|scss|vue|svelte)';
/**
* File names in a command, by their extension. On Windows a path also has a drive and backslashes
* (`C:\Users\me\shop\src\client.ts`, or `C:/Users/...` in Git Bash): without them only `client.ts`, or a
* path on the wrong drive, would be read.
*/
export function fileWordRe(platform: NodeJS.Platform = process.platform): RegExp {
return platform === 'win32' ? new RegExp(`(?:\\b[A-Za-z]:)?[\\w./\\\\~-]+\\.${CODE_EXT}\\b`, 'g') : new RegExp(`[\\w./-]+\\.${CODE_EXT}\\b`, 'g');
}
const FILE_WORD = fileWordRe();
/** `cd <dir> &&` at the start of a command: where its relative paths start. */
const LEADING_CD = /^\s*cd\s+(["']?)([^"'&;|]+?)\1\s*(?:&&|;)/;
/**
* A test, build or type check, as typed: `npm test`, `go test`, `pytest`,
* `npx tsc`, `make`. The match is the command's name for itself, so two runs
* of `go test` with different flags are the same check.
*/
const CHECK =
/(?:^|[;&|(]\s*|\s)((?:npx\s+|bunx\s+|pnpm\s+exec\s+)?(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:test|build|lint|typecheck|check)(?::[\w-]+)?|go\s+(?:test|build|vet)|cargo\s+(?:test|build|check|clippy)|python3?\s+-m\s+(?:pytest|unittest)|pytest|tsc|jest|vitest|mocha|rspec|node\s+--test|deno\s+test|swift\s+(?:test|build)|dotnet\s+(?:test|build)|mix\s+test|mvn\s+[\w:-]*(?:test|verify|package)|\.?\/?gradlew?\s+[\w:-]*(?:test|build)|make(?:\s+(?!-)[\w-]+)?|eslint|ruff|golangci-lint))(?=$|[\s;&|)])/;
/** Output that says a check failed even when a pipe (`| tail`) hid its exit code. */
const FAILED_OUTPUT =
/\b\d+ (?:failed|failing)\b|^FAIL\b|\bFAILED\b|^# fail [1-9]|\bpanic:|Traceback \(most recent|\berror TS\d+|npm ERR!|\bBUILD FAILED\b|\bcompilation failed\b|^error(?:\[E\d+\])?:/m;
const ZERO_FAILED = /\b0 (?:failed|failing)\b|^# fail 0\b/m;
const UNDO = /\bgit\s+(?:restore|revert|reset\s+--hard|checkout\s+(?:\S+\s+)?--\s)/;
const SHIP = /\b(git\s+commit|git\s+push|gh\s+pr\s+create)\b/;
/** Commands that set tools up rather than work on the repo. */
const SETUP = /(?:^|[\s;&|])(?:trail|graft|npx\s+(?:-y\s+)?@(?:trailhq|nanonets)\/[\w-]+)\s|(?:npm|pnpm|yarn|bun)\s+(?:i|install|add|uninstall)\b|\bbrew\s+install\b|\bpip3?\s+install\b/;
/** The person correcting the agent: at the start of their message, or a rule stated in it. */
const CORRECTION_LEAD = /^\s*(?:no|nope|nah|wrong|actually|don't|dont|do not|never|stop|not (?:that|this|like that|quite)|that's (?:not|wrong)|that is (?:not|wrong))\b[\s,.!:;-]/i;
const CORRECTION_RULE =
/\b(?:instead of|instead,|use \S+ instead|we (?:always |usually |never )?(?:use|do|don't|keep|put|run)\b|not like that|that's not how|should(?:n't| not) (?:be|use)|you (?:forgot|missed|broke)\b)/i;
/** A clarification, not a correction: "no, I mean the other file". */
const CLARIFY = /\bi mean(?:t)?\b|\bi was (?:just )?asking\b|\bjust asking\b/i;
/** The person picking one of the options the agent offered. */
const PICK =
/^\s*(?:(?:option|choice|plan)\s*)?(?:[1-9]|[a-d])\s*[.)!]?\s*(?:please|pls)?\s*$|^\s*(?:let'?s |go with |use |pick |do |take |yes,? )?(?:the )?(?:first|second|third|last|1st|2nd|3rd|(?:option|choice|plan)\s*[a-d1-9])\b|^\s*go with\b/i;
const OPTION_LINE = /^\s*(?:\d+[.)]|[A-D][.)]|[-*]\s+\*\*(?:option|choice)|(?:option|choice)\s+[A-D1-9]\b)/gim;
interface ToolEvent {
at: number;
uuid: string;
name: string;
input: any;
id: string;
/** The session's folder when the call was made, as the transcript records it. */
cwd?: string;
}
interface ToolResult {
error: boolean;
text: string;
}
interface Said {
at: number;
uuid: string;
text: string;
}
function textOf(content: unknown): string {
if (typeof content === 'string') return content;
if (Array.isArray(content)) return content.map((c: any) => (typeof c?.text === 'string' ? c.text : '')).join('\n');
return '';
}
/** What the person typed, or null: tool results, hook feedback and system lines aren't typed. */
function typed(e: any): string | null {
if (e?.type !== 'user' || e?.isMeta) return null;
const content = e?.message?.content;
const text =
typeof content === 'string'
? content
: Array.isArray(content) && content.some((b: any) => b?.type === 'text')
? content.filter((b: any) => b?.type === 'text').map((b: any) => String(b.text ?? '')).join('\n')
: null;
if (text === null) return null;
const t = text.trim();
if (!t || t.startsWith('<') || t.startsWith('[Request interrupted') || t.startsWith('Caveat:') || /^Stop hook feedback/i.test(t)) return null;
return t;
}
/** `"no, use a worktree for…"`: the first line, short, safe inside double quotes. */
export function quoted(s: string, n = 60): string {
const line = s.split('\n')[0]!.trim().replace(/"/g, "'");
return line.length > n ? `${line.slice(0, n - 1).trimEnd()}…` : line;
}
/**
* Every sign since the session's last saved learning, best first. `repo` is
* the folder the session works in, to tell its code from trail's files and
* from files outside it.
*/
export function noteSignals(jsonl: string, repo: string): NoteSignal[] {
const tools: ToolEvent[] = [];
const results = new Map<string, ToolResult>();
const prompts: Said[] = [];
const said: Said[] = [];
let at = 0;
let agentSpoke = false;
/** Where the turn that just ended began: the person's last message. */
let turn: Said | null = null;
for (const line of jsonl.split('\n')) {
if (!line.trim()) continue;
let e: any;
try {
e = JSON.parse(line);
} catch {
continue;
}
at++;
const uuid = typeof e?.uuid === 'string' ? e.uuid : `#${at}`;
const content = e?.message?.content;
const blocks: any[] = Array.isArray(content) ? content : [];
if (e?.type === 'assistant') {
for (const b of blocks) {
if (b?.type === 'tool_use')
tools.push({ at, uuid, name: String(b.name ?? ''), input: b.input ?? {}, id: String(b.id ?? ''), cwd: typeof e.cwd === 'string' ? e.cwd : undefined });
else if (b?.type === 'text' && typeof b.text === 'string') said.push({ at, uuid, text: b.text });
}
if (blocks.length) agentSpoke = true;
continue;
}
for (const b of blocks) {
if (b?.type === 'tool_result') results.set(String(b.tool_use_id ?? ''), { error: b.is_error === true, text: textOf(b.content) });
}
const t = typed(e);
if (t !== null) turn = { at, uuid, text: t };
// The session's first message can't correct anything.
if (t !== null && agentSpoke) prompts.push({ at, uuid, text: t });
}
// Start after the last learning that was saved (a note the gate turned away doesn't count).
let from = 0;
for (const t of tools) {
const cmd = typeof t.input?.command === 'string' ? t.input.command : '';
if (t.name === 'Bash' && NOTE_CALL.test(cmd) && results.get(t.id)?.error !== true) from = t.at;
}
const since = <T extends { at: number }>(xs: T[]) => xs.filter((x) => x.at > from);
const work = since(tools);
const inRepo = (file: unknown): string | null => {
if (typeof file !== 'string' || !file) return null;
const rel = isAbsolute(file) ? relative(repo, file) : file;
if (!rel || rel.startsWith('..') || isAbsolute(rel)) return null;
const p = rel.split(sep).join('/');
return trailOwnPath(p) ? null : p;
};
const bash = (t: ToolEvent) => (t.name === 'Bash' && typeof t.input?.command === 'string' ? (t.input.command as string) : null);
/** The repo file a shell command wrote, '' when it wrote one this can't name, null when it wrote none. */
const shellEdit = (t: ToolEvent): string | null => {
const c = bash(t);
if (!c || !BASH_WRITE.test(c) || results.get(t.id)?.error) return null;
const cd = LEADING_CD.exec(c)?.[2]?.trim();
const base = cd ? resolve(t.cwd ?? repo, cd) : (t.cwd ?? repo);
let ownOnly = false;
for (const w of c.match(FILE_WORD) ?? []) {
for (const at of isAbsolute(w) ? [w] : [resolve(base, w), resolve(repo, w)]) {
if (!existsSync(at)) continue;
const p = inRepo(at);
if (p) return p;
ownOnly = true;
}
}
// Writing only trail's own files (settings, learnings) is setup, not a fix.
return ownOnly ? null : '';
};
const codeEdit = (t: ToolEvent): string | null => (EDIT_TOOLS.has(t.name) ? inRepo(t.input?.file_path ?? t.input?.notebook_path) : shellEdit(t));
/** Work on the repo after `at`: a code edit, or a command that isn't setting tools up. */
const setupOnly = (c: string) => c.split(/&&|\|\||;/).every((part) => !part.trim() || SETUP.test(` ${part.trim()} `) || NOTE_CALL.test(part));
const workedAfter = (when: number) => work.some((t) => t.at > when && (codeEdit(t) !== null || ((c) => c !== null && !setupOnly(c))(bash(t))));
const out: NoteSignal[] = [];
// fixed: the same check failed, then passed after an edit to the code.
const checks = work
.map((t) => {
const c = bash(t);
const m = c ? CHECK.exec(c) : null;
const r = results.get(t.id);
if (!m || !r) return null;
const failed = r.error || (FAILED_OUTPUT.test(r.text) && !ZERO_FAILED.test(r.text));
return { t, name: m[1]!.replace(/\s+/g, ' ').trim(), failed };
})
.filter((x): x is { t: ToolEvent; name: string; failed: boolean } => x !== null);
for (let i = checks.length - 1; i >= 0; i--) {
const pass = checks[i]!;
if (pass.failed) continue;
const fails = checks.slice(0, i).filter((c) => c.failed && c.name === pass.name);
if (!fails.length) continue;
const firstFail = fails[0]!.t.at;
const edits = work.filter((t) => t.at > firstFail && t.at < pass.t.at).map(codeEdit).filter((f): f is string => f !== null);
if (!edits.length) continue;
const times = fails.length === 1 ? 'once' : `${fails.length} times`;
const file = [...edits].reverse().find((f) => f !== '');
// Keyed on the episode, the first pass after the last failure: a rerun that passes again is the same sign.
const lastFail = fails[fails.length - 1]!.t.at;
const first = checks.slice(0, i).find((c) => !c.failed && c.name === pass.name && c.t.at > lastFail) ?? pass;
out.push({ kind: 'fixed', key: `fixed:${first.t.uuid}`, what: `${pass.name} failed ${times}, then passed after your change${file ? ` to ${file}` : ''}.` });
break;
}
// corrected: the person set the agent straight, and it went on to change things.
for (const p of since(prompts).reverse()) {
if (CLARIFY.test(p.text) || !(CORRECTION_LEAD.test(p.text) || CORRECTION_RULE.test(p.text))) continue;
if (!workedAfter(p.at)) continue;
out.push({ kind: 'corrected', key: `corrected:${p.uuid}`, what: `The user corrected you ("${quoted(p.text)}").` });
break;
}
// undone: an edit thrown away, which is an approach ruled out.
for (const t of [...work].reverse()) {
const c = bash(t);
if (!c || !UNDO.test(c) || results.get(t.id)?.error) continue;
const paths = c.split(/\s+/).filter((w) => /[/.]/.test(w) && !w.startsWith('-') && !/^(?:HEAD|origin)\b/.test(w));
if (paths.length && paths.every((w) => trailOwnPath(w.replace(/^\.\//, '')))) continue;
out.push({ kind: 'undone', key: `undone:${t.uuid}`, what: `You undid a change (\`${quoted(c, 50)}\`).` });
break;
}
// chose: the person picked one of the agent's options, and it built that one.
const picked = (): NoteSignal | null => {
for (const t of [...work].reverse()) {
if (t.name !== 'AskUserQuestion') continue;
const r = results.get(t.id);
if (!r || r.error || !workedAfter(t.at)) continue;
const answer = r.text.replace(/^[^:]*answered[^:]*:\s*/i, '');
return { kind: 'chose', key: `chose:${t.uuid}`, what: `The user picked one of your options ("${quoted(answer)}").` };
}
for (const p of since(prompts).reverse()) {
if (p.text.length > 80 || !PICK.test(p.text)) continue;
const offer = [...said].reverse().find((s) => s.at < p.at);
if (!offer || !offer.text.includes('?') || (offer.text.match(OPTION_LINE) ?? []).length < 2) continue;
if (!workedAfter(p.at)) continue;
return { kind: 'chose', key: `chose:${p.uuid}`, what: `The user picked one of your options ("${quoted(p.text)}").` };
}
return null;
};
const choice = picked();
if (choice) out.push(choice);
// shipped: the work went into a commit, a push or a PR with no learning beside it.
if (work.some((t) => codeEdit(t) !== null)) {
for (const t of [...work].reverse()) {
const c = bash(t);
const m = c ? SHIP.exec(c) : null;
if (!m || results.get(t.id)?.error) continue;
const verb = m[1]!.startsWith('gh') ? 'opened a PR for' : m[1]!.endsWith('push') ? 'pushed' : 'committed';
out.push({ kind: 'shipped', key: `shipped:${t.uuid}`, what: `You ${verb} this work, and no learning went with it.` });
break;
}
}
// explored: this turn read a lot to find its answer. Asked once a turn, and never for reading trail's own files.
const start = Math.max(from, turn?.at ?? 0);
let reading = 0;
for (const t of work) {
if (t.at <= start) continue;
const r = results.get(t.id);
if (!r || r.error) continue;
for (const m of r.text.matchAll(TRAIL_SAVED)) reading += Number(m[1]!.replace(/,/g, '')) || 0;
if (!READ_TOOLS.has(t.name)) continue;
if (t.name === 'Read' && inRepo(t.input?.file_path) === null) continue;
reading += Math.round(r.text.length / 4);
}
if (reading >= NOTE_WORTHY_READING) {
out.push({ kind: 'explored', key: `explored:${turn?.uuid ?? `#${start}`}`, what: `This turn took about ${Math.round(reading / 1000)}k tokens of reading to work out.` });
}
return out;
}
const SAVE = '`trail note --title "<the fact, not the task>"`';
const CLOSE = 'Sections: ## Decided, ## Tried and ruled out, ## Watch out. A summary, never a transcript, nothing secret. Then finish as trail\'s output asks.';
/** What the agent is told: the sign first, since Claude Code folds long hook output to its first lines. */
export function noteAsk(s: NoteSignal): string {
const skip = 'Nothing worth keeping? Say so and stop.';
const first =
s.kind === 'fixed'
? `${s.what} If the cause isn't obvious from the diff, save it: ${SAVE}, naming the file and the why. ${skip}`
: s.kind === 'corrected'
? `${s.what} Save the rule so nobody has to say it again: ${SAVE}, naming the file it's about; add --personal if it's about how this person likes to work. ${skip}`
: s.kind === 'undone'
? `${s.what} If you dropped an approach, save why under ## Tried and ruled out: ${SAVE}, naming the file. ${skip}`
: s.kind === 'chose'
? `${s.what} If the choice matters to the next person, save it under ## Decided, with the options you dropped and why under ## Tried and ruled out: ${SAVE}. ${skip}`
: s.kind === 'explored'
? `${s.what} If it found where something lives or why it works the way it does, and the code won't say so plainly, save it: ${SAVE}, naming the files. ${skip}`
: `${s.what} If the session found what the diff won't tell the next person (a cause, a dropped approach, a rule), save it now so it ships with the change: ${SAVE}. ${skip}`;
return `[trail] ${first}\n${CLOSE}`;
}