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
/**
* What the current agent session spent working something out, for a note's
* cost line: active minutes, and tokens.
*
* Read from Claude Code's own transcript, which it keeps as JSONL under
* `~/.claude/projects/<the repo path, every other character as "-">/`, one
* file per session. The one being written right now is the newest. Other
* agents keep no transcript we can read, so their notes carry no cost unless
* the agent passes `--minutes` / `--tokens`.
*
* Counted from the session's last finished `trail note` (or its start), so two
* notes from one long session don't both claim the same work. Within that,
* from the turn where the work the note names first came up: the first prompt
* or tool call that mentions one of its files, symbols or commands. A long
* session that did other things first (a Slack search, a merge) doesn't charge
* them to this learning. When nothing matches, only the last 30 active
* minutes count, never the whole stretch. Tokens are the
* ones the model actually processed fresh: input, cache writes and output.
* Cache reads are left out, since they re-read the same context every turn and
* would make an hour's work look like millions. Minutes are active minutes: a
* gap of more than ten minutes between two entries counts as nothing, so a
* session left open over lunch doesn't claim the lunch.
*/
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { homedir } from "node:os";
import { dirname, join, resolve } from "node:path";
export interface SessionCost {
minutes: number;
tokens: number;
/** When the stretch since the last note began, epoch ms. */
startedAt: number;
/** When the counted work began, epoch ms: the first mention of what the note is about. */
countedFrom: number;
/** Files the agent edited or wrote in that stretch, absolute, in order. */
edited: string[];
/** Files the agent opened with Read in that stretch, absolute, in order. */
read: string[];
}
const IDLE_MS = 10 * 60 * 1000;
/** With nothing in the transcript naming what the note is about, at most this much active time counts. */
export const FALLBACK_ACTIVE_MS = 30 * 60 * 1000;
/** A transcript untouched this long belongs to some earlier session. */
const ACTIVE_MS = 30 * 60 * 1000;
export function claudeProjectDir(repo: string, home: string = homedir()): string {
return join(home, ".claude", "projects", repo.replace(/[^A-Za-z0-9]/g, "-"));
}
/**
* The project folder of the session that `dir` is part of: `dir`'s own, or
* the nearest ancestor's. A note saved from a subfolder, or from one repo of
* a session started in the folder above several, still finds its session.
*/
function sessionProjectDir(dir: string, home?: string): string | null {
for (let d = resolve(dir); ; d = dirname(d)) {
const p = claudeProjectDir(d, home);
if (existsSync(p)) return p;
if (dirname(d) === d) return null;
}
}
/** The transcript of the session running in `repo` now, or null. */
export function currentTranscript(repo: string, home?: string, now = Date.now()): string | null {
const dir = sessionProjectDir(repo, home);
if (!dir) return null;
let best: { path: string; mtime: number } | null = null;
let files: string[];
try {
files = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
} catch {
return null;
}
for (const f of files) {
try {
const mtime = statSync(join(dir, f)).mtimeMs;
if (!best || mtime > best.mtime) best = { path: join(dir, f), mtime };
} catch {
/* gone */
}
}
return best && now - best.mtime <= ACTIVE_MS ? best.path : null;
}
interface Entry {
type?: string;
timestamp?: string;
message?: {
id?: string;
usage?: { input_tokens?: number; cache_creation_input_tokens?: number; output_tokens?: number };
content?: unknown;
};
}
function blocks(e: Entry): Array<Record<string, unknown>> {
const c = e.message?.content;
return Array.isArray(c) ? (c as Array<Record<string, unknown>>) : [];
}
/** Claude Code's tools that change a file, each naming it in `file_path` (`notebook_path` for notebooks). */
const EDIT_TOOLS = new Set(["Edit", "MultiEdit", "Write", "NotebookEdit"]);
export const NOTE_CALL = /(^|[|&;]\s*|\s)(npx\s+(-y\s+)?(@trailhq\/|@nanonets\/)?)?(trail|graft)\s+note\b/;
/** Words too common to say what a note is about: they'd match the first turn of any session. */
const TOO_COMMON = new Set(["trail", "graft", "claude", "true", "false", "null", "main", "master", "node", "git", "npm", "test", "tests"]);
/**
* What a note is about, as strings a transcript would show when that work
* began: the files it names (path and file name) and anything it puts in
* backticks, such as a symbol, a command or a setting.
*/
export function aboutTerms(body: string, files: string[] = []): string[] {
const terms = new Set<string>();
for (const f of files) {
const path = f.split("#")[0]!.trim();
if (!path) continue;
terms.add(path);
const name = path.split("/").pop()!;
if (name.length >= 4) terms.add(name);
}
for (const m of body.matchAll(/`([^`\n]{3,80})`/g)) {
const t = m[1]!.trim().replace(/\(\)$/, "");
if (t.length >= 4 && !TOO_COMMON.has(t.toLowerCase()) && specific(t)) terms.add(t);
}
return [...terms];
}
/**
* Whether a backticked term names something specific enough to date the work:
* a path or file (`a/b`, `x.ts`), or an identifier (`dropHtmlComments`,
* `repo_id`, `check-ignore`). A phrase or a plain word (`trail init`,
* `publish`) comes up in any session about the product, so it would date
* the work to the session's first turn.
*/
function specific(t: string): boolean {
if (/\s/.test(t)) return false;
return /[\/._]|[a-z][A-Z]|\w-\w/.test(t);
}
/** A prompt the person typed, as opposed to a tool's result coming back. */
function promptText(e: Entry): string | null {
if (e.type !== "user") return null;
const c = e.message?.content;
if (typeof c === "string") return c;
if (!Array.isArray(c) || c.some((b) => (b as { type?: string }).type === "tool_result")) return null;
const text = c.filter((b) => (b as { type?: string }).type === "text").map((b) => String((b as { text?: unknown }).text ?? "")).join("\n");
return text || null;
}
/**
* Index into `entries` where the work on a note began: the prompt of the turn
* whose prompt or tool calls first mention one of `terms`, never earlier than
* `from`. A `trail note` call doesn't count: the one being saved names them all.
*/
function firstMention(entries: Entry[], from: number, terms: string[]): number | null {
if (!terms.length) return null;
let turn = from;
for (let i = from; i < entries.length; i++) {
const e = entries[i]!;
const prompt = promptText(e);
if (prompt !== null) turn = i;
const said = [prompt ?? ""];
for (const b of blocks(e)) {
if (b.type !== "tool_use") continue;
const input = JSON.stringify(b.input ?? {});
if (NOTE_CALL.test(input)) continue;
said.push(input);
}
if (said.some((s) => s && terms.some((t) => s.includes(t)))) return turn;
}
return null;
}
/**
* The cost of one transcript since its last finished note. Pure, for tests:
* `text` is the JSONL, `now` closes the last stretch when the transcript ends
* mid-turn (it always does: the note call itself is in flight). `terms` are
* what the note is about (see `aboutTerms`); without them the whole stretch
* since the last note counts, as before.
*/
export function costFromTranscript(text: string, now = Date.now(), terms?: string[]): SessionCost | null {
const entries: Entry[] = [];
for (const line of text.split("\n")) {
if (!line.trim()) continue;
try {
entries.push(JSON.parse(line) as Entry);
} catch {
/* a half-written last line */
}
}
// A note call is finished once its tool_result is in the transcript; the
// call that is running right now has none yet, so it never counts as the
// boundary.
const noteCalls = new Set<string>();
let boundary = -1;
entries.forEach((e, i) => {
for (const b of blocks(e)) {
if (b.type === "tool_use" && typeof b.id === "string") {
const cmd = (b.input as { command?: unknown } | undefined)?.command;
if (typeof cmd === "string" && NOTE_CALL.test(cmd)) noteCalls.add(b.id);
}
if (b.type === "tool_result" && typeof b.tool_use_id === "string" && noteCalls.has(b.tool_use_id)) boundary = i;
}
});
const after = entries.slice(boundary + 1);
const since = after.filter((e) => e.timestamp && Number.isFinite(Date.parse(e.timestamp)));
if (since.length === 0) return null;
const startedAt = Date.parse(since[0]!.timestamp!);
// Where this note's work began within the stretch.
let counted = since;
if (terms) {
const at = firstMention(entries, boundary + 1, terms);
const stretch = new Set(since);
counted = at !== null ? entries.slice(at).filter((e) => stretch.has(e)) : lastActive(since, now, FALLBACK_ACTIVE_MS);
if (counted.length === 0) counted = since.slice(-1);
}
const times = counted.map((e) => Date.parse(e.timestamp!));
times.push(now);
let activeMs = 0;
for (let i = 1; i < times.length; i++) {
const gap = times[i]! - times[i - 1]!;
if (gap > 0 && gap <= IDLE_MS) activeMs += gap;
}
// Claude Code writes one line per content block, each repeating its
// message's usage, so a message is counted once by its id.
const seen = new Set<string>();
let tokens = 0;
for (const e of counted) {
if (e.type !== "assistant" || !e.message?.usage) continue;
const id = e.message.id;
if (id) {
if (seen.has(id)) continue;
seen.add(id);
}
const u = e.message.usage;
tokens += (u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.output_tokens ?? 0);
}
const edited: string[] = [];
const read: string[] = [];
for (const e of after) {
for (const b of blocks(e)) {
if (b.type !== "tool_use") continue;
const input = (b.input ?? {}) as { file_path?: unknown; notebook_path?: unknown };
const file = typeof input.file_path === "string" ? input.file_path : input.notebook_path;
if (typeof file !== "string" || !file) continue;
if (EDIT_TOOLS.has(String(b.name)) && !edited.includes(file)) edited.push(file);
else if (b.name === "Read" && !read.includes(file)) read.push(file);
}
}
return { minutes: Math.max(1, Math.round(activeMs / 60_000)), tokens, startedAt, countedFrom: times[0]!, edited, read };
}
/** The entries in the last `budgetMs` of active time before `now`, oldest first. */
function lastActive(entries: Entry[], now: number, budgetMs: number): Entry[] {
let used = 0;
let prev = now;
for (let i = entries.length - 1; i >= 0; i--) {
const t = Date.parse(entries[i]!.timestamp!);
const gap = prev - t;
if (gap > 0 && gap <= IDLE_MS) used += gap;
if (used > budgetMs) return entries.slice(i + 1);
prev = t;
}
return entries;
}
/** The running session's cost in `repo`, or null when there is no transcript to read. */
export function currentSessionCost(repo: string, home?: string, now = Date.now(), terms?: string[]): SessionCost | null {
const path = currentTranscript(repo, home, now);
if (!path) return null;
try {
return costFromTranscript(readFileSync(path, "utf8"), now, terms);
} catch {
return null;
}
}