Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

ask: build-time file sizes → tokens-saved estimate in --source; auto-inject spans + savings via prompt hook + statusline total

anirudhkumar-nanonetsa1ddabcbb81c
diff --git a/bench/token-ab.ts b/bench/token-ab.ts
new file mode 100644
index 00000000..99f2c6eb
--- /dev/null
+++ b/bench/token-ab.ts
@@ -0,0 +1,297 @@
+/**
+ * token-ab.ts — a manual A/B harness to see whether graft saves an agent tokens.
+ *
+ * Same question, same model, two arms:
+ * COLD — the agent gets only `search` + `read_file` tools and must explore
+ * the repo itself (what a normal coding agent does).
+ * GRAFT — the agent gets the SAME tools, but the `graft ask --source` pack is
+ * pasted into its context up front, so it can answer without exploring.
+ *
+ * It prints a side-by-side metrics table (tokens, LLM round-trips, tool calls,
+ * files opened, wall-clock) and BOTH final answers, so you judge equivalence.
+ *
+ * Prereqs:
+ * 1. OPENROUTER_API_KEY in context-engine/.env (already there).
+ * 2. graft built in the target repo: cd <REPO> && graft build
+ *
+ * Run: npx tsx bench/token-ab.ts
+ * Tune: edit the CONFIG block, or override via env (REPO, QUESTION, MODEL, MAX_STEPS).
+ */
+import "dotenv/config";
+import OpenAI from "openai";
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, relative, isAbsolute } from "node:path";
+
+// ─────────────────────────── CONFIG (edit freely) ───────────────────────────
+const CONFIG = {
+ REPO: process.env.REPO ?? "/Users/anirudh/Documents/assign/frontend",
+ QUESTION:
+ process.env.QUESTION ??
+ "When a user sends a message to an agent in the chat UI, trace the full path end to end: " +
+ "which component handles the submit, how the message reaches the backend API, how the optimistic " +
+ "update and the polling query stay in sync via the React Query cache key, where the agent is " +
+ "resolved from the route, and where a quota/402 billing error is handled. " +
+ "List the specific files and functions in order.",
+ MODEL: process.env.MODEL ?? "openai/gpt-4o-mini",
+ MAX_STEPS: Number(process.env.MAX_STEPS ?? 14), // cap on agent tool-loop round-trips
+ SEARCH_MAX_LINES: 60, // cap rows returned per search
+ READ_MAX_LINES: 400, // cap lines returned per read_file
+ READ_MAX_CHARS: 12_000, // hard char cap per read_file
+ // Optional cost estimate: set $ per 1M tokens for your model to see a $ column.
+ PRICE_IN_PER_M: Number(process.env.PRICE_IN_PER_M ?? 0),
+ PRICE_OUT_PER_M: Number(process.env.PRICE_OUT_PER_M ?? 0),
+};
+// ─────────────────────────────────────────────────────────────────────────────
+
+const KEY = process.env.OPENROUTER_API_KEY;
+if (!KEY) {
+ console.error("✗ OPENROUTER_API_KEY not set (expected in context-engine/.env).");
+ process.exit(1);
+}
+if (!existsSync(CONFIG.REPO)) {
+ console.error(`✗ REPO not found: ${CONFIG.REPO}`);
+ process.exit(1);
+}
+
+const client = new OpenAI({ apiKey: KEY, baseURL: "https://openrouter.ai/api/v1" });
+
+interface Metrics {
+ arm: string;
+ llmCalls: number;
+ promptTokens: number;
+ completionTokens: number;
+ toolCalls: number;
+ filesRead: Set<string>;
+ ms: number;
+ answer: string;
+}
+
+const SYSTEM =
+ "You are a senior engineer answering a question about an unfamiliar codebase. " +
+ "Be accurate and cite specific files and functions. When you have enough to answer, " +
+ "STOP calling tools and write the final answer as prose. Do not pad.";
+
+const TOOLS: OpenAI.Chat.Completions.ChatCompletionTool[] = [
+ {
+ type: "function",
+ function: {
+ name: "search",
+ description:
+ "Regex search across the repo's source (ripgrep). Returns matching file:line: text rows.",
+ parameters: {
+ type: "object",
+ properties: { pattern: { type: "string", description: "regex or literal to search for" } },
+ required: ["pattern"],
+ },
+ },
+ },
+ {
+ type: "function",
+ function: {
+ name: "read_file",
+ description: "Read a source file (optionally a line range) relative to the repo root.",
+ parameters: {
+ type: "object",
+ properties: {
+ path: { type: "string", description: "repo-relative path, e.g. src/components/chat/TaskFeed.tsx" },
+ start_line: { type: "number", description: "1-based start line (optional)" },
+ end_line: { type: "number", description: "1-based end line (optional)" },
+ },
+ required: ["path"],
+ },
+ },
+ },
+];
+
+// ── tool implementations (sandboxed to REPO) ────────────────────────────────
+function runSearch(pattern: string): string {
+ const args = [
+ "--no-heading", "-n", "-S", "--max-count", "40",
+ "-g", "*.ts", "-g", "*.tsx", "-g", "!node_modules",
+ pattern, CONFIG.REPO,
+ ];
+ let out = "";
+ try {
+ out = execFileSync("rg", args, { encoding: "utf8", maxBuffer: 8 << 20 });
+ } catch (e: any) {
+ // rg exits 1 on "no matches"; also handle rg-not-installed by falling back to grep.
+ if (e?.code === "ENOENT") {
+ try {
+ out = execFileSync(
+ "grep",
+ ["-rniE", "--include=*.ts", "--include=*.tsx", "--exclude-dir=node_modules", pattern, CONFIG.REPO],
+ { encoding: "utf8", maxBuffer: 8 << 20 },
+ );
+ } catch (g: any) {
+ out = g?.stdout?.toString() ?? "";
+ }
+ } else {
+ out = e?.stdout?.toString() ?? "";
+ }
+ }
+ const lines = out.split("\n").filter(Boolean).map((l) => l.replace(CONFIG.REPO + "/", ""));
+ if (lines.length === 0) return "(no matches)";
+ const clipped = lines.slice(0, CONFIG.SEARCH_MAX_LINES);
+ const note = lines.length > clipped.length ? `\n… ${lines.length - clipped.length} more rows omitted` : "";
+ return clipped.join("\n") + note;
+}
+
+function runRead(path: string, start?: number, end?: number): { text: string; resolved: string } {
+ const abs = isAbsolute(path) ? resolve(path) : resolve(CONFIG.REPO, path);
+ const rel = relative(CONFIG.REPO, abs);
+ if (rel.startsWith("..") || isAbsolute(rel)) return { text: `(refused: ${path} is outside the repo)`, resolved: rel };
+ if (!existsSync(abs)) return { text: `(not found: ${rel})`, resolved: rel };
+ let content = readFileSync(abs, "utf8");
+ const allLines = content.split("\n");
+ let lines = allLines;
+ if (start || end) {
+ const s = Math.max(1, start ?? 1);
+ const e = Math.min(allLines.length, end ?? allLines.length);
+ lines = allLines.slice(s - 1, e).map((l, i) => `${s + i}\t${l}`);
+ }
+ if (lines.length > CONFIG.READ_MAX_LINES) lines = lines.slice(0, CONFIG.READ_MAX_LINES);
+ let text = lines.join("\n");
+ if (text.length > CONFIG.READ_MAX_CHARS) text = text.slice(0, CONFIG.READ_MAX_CHARS) + "\n… (truncated)";
+ return { text, resolved: rel };
+}
+
+// ── the agent loop, shared by both arms ──────────────────────────────────────
+async function runAgent(arm: string, extraContext: string | null): Promise<Metrics> {
+ const m: Metrics = {
+ arm, llmCalls: 0, promptTokens: 0, completionTokens: 0, toolCalls: 0,
+ filesRead: new Set(), ms: 0, answer: "",
+ };
+ const t0 = Date.now();
+
+ const userParts = [`QUESTION:\n${CONFIG.QUESTION}`];
+ if (extraContext) {
+ userParts.push(
+ "\nYou have been given a pre-computed context pack from a code-graph tool below. " +
+ "Prefer it; only use the search/read_file tools if it is genuinely insufficient.\n\n" +
+ "=== CONTEXT PACK ===\n" + extraContext,
+ );
+ }
+ const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
+ { role: "system", content: SYSTEM },
+ { role: "user", content: userParts.join("\n") },
+ ];
+
+ for (let step = 0; step < CONFIG.MAX_STEPS; step++) {
+ const resp = await client.chat.completions.create({
+ model: CONFIG.MODEL,
+ temperature: 0,
+ messages,
+ tools: TOOLS,
+ tool_choice: "auto",
+ });
+ m.llmCalls++;
+ m.promptTokens += resp.usage?.prompt_tokens ?? 0;
+ m.completionTokens += resp.usage?.completion_tokens ?? 0;
+
+ const msg = resp.choices[0].message;
+ messages.push(msg as OpenAI.Chat.Completions.ChatCompletionMessageParam);
+
+ const calls = msg.tool_calls ?? [];
+ if (calls.length === 0) {
+ m.answer = msg.content ?? "(empty)";
+ break;
+ }
+
+ for (const call of calls) {
+ if (call.type !== "function") continue;
+ m.toolCalls++;
+ let result = "";
+ try {
+ const args = JSON.parse(call.function.arguments || "{}");
+ if (call.function.name === "search") {
+ result = runSearch(String(args.pattern ?? ""));
+ } else if (call.function.name === "read_file") {
+ const r = runRead(String(args.path ?? ""), args.start_line, args.end_line);
+ if (existsSync(resolve(CONFIG.REPO, String(args.path ?? "")))) m.filesRead.add(r.resolved);
+ result = r.text;
+ } else {
+ result = `(unknown tool ${call.function.name})`;
+ }
+ } catch (e: any) {
+ result = `(tool error: ${e?.message ?? e})`;
+ }
+ messages.push({ role: "tool", tool_call_id: call.id, content: result });
+ }
+ if (step === CONFIG.MAX_STEPS - 1) m.answer = "(hit MAX_STEPS without a final answer)";
+ }
+
+ m.ms = Date.now() - t0;
+ return m;
+}
+
+// ── graft pack for the GRAFT arm ─────────────────────────────────────────────
+function graftPack(): { pack: string; ms: number } {
+ const t0 = Date.now();
+ if (!existsSync(resolve(CONFIG.REPO, "graft"))) {
+ console.error(`✗ no graft/ index in ${CONFIG.REPO}. Run: cd ${CONFIG.REPO} && graft build`);
+ process.exit(1);
+ }
+ const pack = execFileSync("graft", ["ask", CONFIG.QUESTION, CONFIG.REPO, "--source"], {
+ encoding: "utf8",
+ maxBuffer: 16 << 20,
+ });
+ return { pack, ms: Date.now() - t0 };
+}
+
+function cost(m: Metrics): string {
+ if (!CONFIG.PRICE_IN_PER_M && !CONFIG.PRICE_OUT_PER_M) return "—";
+ const c = (m.promptTokens / 1e6) * CONFIG.PRICE_IN_PER_M + (m.completionTokens / 1e6) * CONFIG.PRICE_OUT_PER_M;
+ return "$" + c.toFixed(4);
+}
+
+function row(label: string, a: string | number, b: string | number): string {
+ return `${label.padEnd(22)} ${String(a).padStart(14)} ${String(b).padStart(14)}`;
+}
+
+async function main() {
+ console.log(`\nREPO: ${CONFIG.REPO}`);
+ console.log(`MODEL: ${CONFIG.MODEL}`);
+ console.log(`QUESTION: ${CONFIG.QUESTION.slice(0, 100)}…\n`);
+
+ console.log("→ generating graft pack (graft ask --source)…");
+ const { pack, ms: graftMs } = graftPack();
+ const packTokEst = Math.round(pack.length / 4); // rough: ~4 chars/token
+ console.log(` pack: ${pack.length} chars (~${packTokEst} tok), produced in ${graftMs}ms ($0, local)\n`);
+
+ console.log("→ running COLD arm (agent explores the repo itself)…");
+ const cold = await runAgent("COLD", null);
+ console.log(` done in ${cold.ms}ms, ${cold.llmCalls} LLM calls\n`);
+
+ console.log("→ running GRAFT arm (agent handed the pack up front)…");
+ const graft = await runAgent("GRAFT", pack);
+ console.log(` done in ${graft.ms}ms, ${graft.llmCalls} LLM calls\n`);
+
+ const totC = cold.promptTokens + cold.completionTokens;
+ const totG = graft.promptTokens + graft.completionTokens;
+ const pct = (a: number, b: number) => (a === 0 ? "—" : `${Math.round((1 - b / a) * 100)}%`);
+
+ console.log("═".repeat(54));
+ console.log(row("metric", "COLD", "GRAFT"));
+ console.log("─".repeat(54));
+ console.log(row("prompt tokens", cold.promptTokens, graft.promptTokens));
+ console.log(row("completion tokens", cold.completionTokens, graft.completionTokens));
+ console.log(row("TOTAL tokens", totC, totG));
+ console.log(row("LLM round-trips", cold.llmCalls, graft.llmCalls));
+ console.log(row("tool calls", cold.toolCalls, graft.toolCalls));
+ console.log(row("files opened", cold.filesRead.size, graft.filesRead.size));
+ console.log(row("wall-clock (ms)", cold.ms, graft.ms));
+ console.log(row("est. cost", cost(cold), cost(graft)));
+ console.log("─".repeat(54));
+ console.log(`token saving with graft: ${pct(totC, totG)} (COLD→GRAFT)`);
+ console.log("═".repeat(54));
+
+ console.log("\n──────── COLD answer ────────\n" + cold.answer);
+ console.log("\n──────── GRAFT answer ────────\n" + graft.answer);
+ console.log("\n(Judge the two answers yourself — the point is equal quality at fewer tokens.)");
+}
+
+main().catch((e) => {
+ console.error(e);
+ process.exit(1);
+});
diff --git a/src/ask/ask.ts b/src/ask/ask.ts
index 1ea98941..f5cbf4e8 100644
--- a/src/ask/ask.ts
+++ b/src/ask/ask.ts
@@ -46,6 +46,10 @@ export interface AskResult {
subject?: string;
hits: AskHit[];
note?: string;
+ /** Token-saving estimate, set only in `--source` (retriever) mode: the whole
+ * size of the distinct files these hits point into, i.e. the baseline cost of
+ * reading them instead of this pack. Computed from file sizes stored at build. */
+ saved?: { files: number; baselineChars: number };
}
const STOP = new Set([
@@ -286,6 +290,39 @@ function inlineSource(root: string, hits: AskHit[]): void {
}
}
+/** Every repo-relative file path a set of hits points into (dedup). A symbol
+ * pointer is `path:span`; a concept pointer is a comma-joined path list. */
+function hitFiles(hits: AskHit[]): Set<string> {
+ const files = new Set<string>();
+ for (const h of hits) {
+ const span = parseSpan(h.pointer);
+ if (span) { files.add(span.path); continue; }
+ for (const p of h.pointer.split(",").map((s) => s.trim()))
+ if (p && !p.includes(" ")) files.add(p);
+ }
+ return files;
+}
+
+/** Baseline = whole size of the files these hits cover, read from the sizes the
+ * build stored on each file node. Zero when the graph predates the `chars` field
+ * (a pre-upgrade index) — the caller then just omits the estimate. */
+function baselineFor(hits: AskHit[], graph: GraphV1 | null): AskResult["saved"] | undefined {
+ if (!graph) return undefined;
+ const size = new Map<string, number>();
+ for (const n of graph.nodes)
+ if (n.kind === "file" && typeof n.chars === "number") size.set(n.path, n.chars);
+
+ let baselineChars = 0;
+ let files = 0;
+ for (const path of hitFiles(hits)) {
+ const c = size.get(path);
+ if (c === undefined) continue;
+ baselineChars += c;
+ files++;
+ }
+ return files > 0 ? { files, baselineChars } : undefined;
+}
+
/** Answer a query from the graft/ graph at `dir`. Deterministic, $0. */
export function ask(dir: string, query: string, opts: AskOptions = {}): AskResult {
const root = resolve(dir);
@@ -300,10 +337,20 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResul
} else {
result = lexical(query, corpus, limit);
}
- if (opts.source) inlineSource(root, result.hits);
+ if (opts.source) {
+ inlineSource(root, result.hits);
+ // The pack is truly substitutive only in retriever mode (spans inlined), so
+ // the "vs reading whole files" estimate is only honest here.
+ result.saved = baselineFor(result.hits, corpus.graph);
+ }
return result;
}
+/** Rough tokens for a byte length (≈ 4 chars/token; good enough for an estimate). */
+function toTokens(chars: number): number {
+ return Math.round(chars / 4);
+}
+
/** Render an {@link AskResult} as a compact markdown context pack. */
export function formatAsk(r: AskResult): string {
const head = `graft ask — "${r.query}" (${r.mode}${r.note ? `: ${r.note}` : ""})`;
@@ -327,5 +374,23 @@ export function formatAsk(r: AskResult): string {
lines.push("");
});
}
- return lines.join("\n").trimEnd() + "\n";
+ const body = lines.join("\n").trimEnd();
+ return body + savingsFooter(r, body) + "\n";
+}
+
+/** The one-line token-saving estimate `ask` appends in retriever mode, so the
+ * agent gets the number for free in the tool output — no extra work on its end.
+ * `packChars` is measured from the rendered body: exactly what the agent reads. */
+function savingsFooter(r: AskResult, body: string): string {
+ if (!r.saved || r.saved.baselineChars <= 0) return "";
+ const pack = toTokens(body.length);
+ const base = toTokens(r.saved.baselineChars);
+ if (base <= pack) return ""; // no saving to claim (tiny files); stay quiet
+ const saved = base - pack;
+ const pct = Math.round((saved / base) * 100);
+ return (
+ `\n\n[graft] tokens saved ≈ ${saved.toLocaleString()} (${pct}%) — this pack ≈ ` +
+ `${pack.toLocaleString()} tok vs reading the ${r.saved.files} source file(s) whole ≈ ` +
+ `${base.toLocaleString()} tok. Estimate (baseline = those files read in full).`
+ );
}
diff --git a/src/claude/format.ts b/src/claude/format.ts
index fb4db79a..0fe852b4 100644
--- a/src/claude/format.ts
+++ b/src/claude/format.ts
@@ -25,7 +25,7 @@ export function freshnessSegment(s: Stats): string {
export function renderStatusline(
stats: Stats | null,
- _session: SessionState | null,
+ session: SessionState | null,
ctx: { ctxPct: number | null },
): string[] {
if (!stats || stats.nodeCount === 0) {
@@ -35,6 +35,8 @@ export function renderStatusline(
const enr = enrichedSegment(stats);
if (enr) top.push(enr);
top.push(freshnessSegment(stats));
+ const saved = session?.savedTokens ?? 0;
+ if (saved > 0) top.push(C.indigo(`~${saved.toLocaleString()} tok saved`));
const bottom: string[] = [];
if (typeof ctx.ctxPct === 'number') bottom.push(C.text(`ctx ${ctx.ctxPct}%`));
@@ -74,18 +76,50 @@ export function formatBlastRadius(w: GraphV1, filePath: string, cap = 8): string
export interface AskJson {
query: string; mode: string;
- hits: { kind: string; title: string; pointer: string; snippet: string; score: number }[];
+ hits: { kind: string; title: string; pointer: string; snippet: string; score: number; code?: string }[];
+ /** Set by `ask --source`: whole size of the files these hits cover (baseline). */
+ saved?: { files: number; baselineChars: number };
}
-export function formatRetrieval(ask: AskJson, cap = 5): string | null {
- const hits = (ask.hits ?? []).slice(0, cap);
- if (!hits.length) return null;
- const lines = hits.map((h) => {
+function tokensOf(chars: number): number { return Math.round(chars / 4); }
+
+/** The retrieval pack body — pointers, snippets, and (in --source mode) the
+ * actual code span for each hit, so the agent reads it here instead of opening
+ * the file. Kept separate so the tokens-saved math can measure this exact text. */
+function retrievalBody(hits: AskJson['hits']): string {
+ const blocks = hits.map((h, i) => {
const ptr = (h.pointer ?? '').split(',')[0].trim();
const snip = (h.snippet ?? '').replace(/\s+/g, ' ').trim().slice(0, 140);
- return ` • ${h.title} — ${ptr} — ${snip}`;
+ let b = ` ${i + 1}. ${h.title} — ${ptr}`;
+ if (snip) b += `\n ${snip}`;
+ if (h.code) b += `\n\`\`\`\n${h.code}\n\`\`\``;
+ return b;
});
- return `[graft] relevant context for this prompt:\n${lines.join('\n')}`;
+ return `[graft] retrieved context — read these spans, do not re-open the files:\n${blocks.join('\n')}`;
+}
+
+/** Tokens saved (baseline − this pack), or 0 when no honest estimate applies. */
+export function retrievalTokensSaved(ask: AskJson, cap = 5): number {
+ const hits = (ask.hits ?? []).slice(0, cap);
+ if (!hits.length || !ask.saved || ask.saved.baselineChars <= 0) return 0;
+ const pack = tokensOf(retrievalBody(hits).length);
+ const base = tokensOf(ask.saved.baselineChars);
+ return base > pack ? base - pack : 0;
+}
+
+export function formatRetrieval(ask: AskJson, cap = 5): string | null {
+ const hits = (ask.hits ?? []).slice(0, cap);
+ if (!hits.length) return null;
+ const body = retrievalBody(hits);
+ const saved = retrievalTokensSaved(ask, cap);
+ if (saved <= 0) return body;
+ const base = tokensOf(ask.saved!.baselineChars);
+ const pct = Math.round((saved / base) * 100);
+ return (
+ `${body}\n[graft] tokens saved ≈ ${saved.toLocaleString()} (${pct}%) — this pack ≈ ` +
+ `${tokensOf(body.length).toLocaleString()} tok vs reading the ${ask.saved!.files} file(s) whole ≈ ` +
+ `${base.toLocaleString()} tok (estimate).`
+ );
}
export function formatOrientation(indexMd: string, budgetBytes = 1500): string {
diff --git a/src/claude/hooks.ts b/src/claude/hooks.ts
index ab800382..1da86cd3 100644
--- a/src/claude/hooks.ts
+++ b/src/claude/hooks.ts
@@ -1,8 +1,8 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
import { execFileSync, spawn } from 'node:child_process';
import { join, basename } from 'node:path';
import { readWiring } from './stats.js';
-import { formatBlastRadius, formatRetrieval, formatOrientation } from './format.js';
+import { formatBlastRadius, formatRetrieval, retrievalTokensSaved, formatOrientation } from './format.js';
import { patchStats, readStats, acquireLock, readSession, writeSession } from './state.js';
function readStdin(): any {
@@ -19,9 +19,16 @@ export function underGraft(dir: string, file: string): boolean {
const rel = file.startsWith(dir) ? file.slice(dir.length) : file;
return rel.replace(/^[/\\]+/, '').replace(/\\/g, '/').startsWith('graft/');
}
+/** Resolve the graft CLI: the repo's own build when present (graft self-hosting),
+ * else the globally-installed `graft` on PATH (any other repo using graft). */
+function graftCli(dir: string): { cmd: string; pre: string[] } {
+ const local = join(dir, 'dist', 'cli.js');
+ return existsSync(local) ? { cmd: process.execPath, pre: [local] } : { cmd: 'graft', pre: [] };
+}
function graftJson(dir: string, args: string[]): any | null {
+ const { cmd, pre } = graftCli(dir);
try {
- const out = execFileSync(process.execPath, [join(dir, 'dist', 'cli.js'), ...args],
+ const out = execFileSync(cmd, [...pre, ...args],
{ cwd: dir, encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] });
return JSON.parse(out);
} catch (e: any) {
@@ -64,11 +71,15 @@ export async function main(event: string): Promise<void> {
}
if (event === 'stop') {
+ // Auto-sync needs graft's own build (sync-run.js). Only graft's self-hosted
+ // repo has it; in any other repo skip rather than spawn a missing script and
+ // get wedged on syncing:true (those repos regen via their own build/CI).
+ const syncRun = join(dir, 'dist', 'claude', 'sync-run.js');
+ if (!existsSync(syncRun)) return;
const stats = readStats(dir);
if (stats?.dirty && acquireLock(dir)) {
patchStats(dir, { syncing: true });
- const child = spawn(process.execPath, [join(dir, 'dist', 'claude', 'sync-run.js'), dir],
- { detached: true, stdio: 'ignore' });
+ const child = spawn(process.execPath, [syncRun, dir], { detached: true, stdio: 'ignore' });
child.unref();
}
return;
@@ -77,7 +88,10 @@ export async function main(event: string): Promise<void> {
if (event === 'prompt') {
const prompt = String(input?.prompt ?? '').trim();
if (prompt.length < 8) return;
- const ask = graftJson(dir, ['ask', prompt, '.', '--json', '-n', '5']);
+ // --source: inline the actual code spans so the injected pack is substitutive
+ // (the agent reads the span here instead of opening the file), and so `ask`
+ // returns the `saved` baseline used for the tokens-saved line.
+ const ask = graftJson(dir, ['ask', prompt, '.', '--json', '--source', '-n', '5']);
if (!ask) return;
const txt = formatRetrieval(ask);
if (!txt) return;
@@ -85,6 +99,10 @@ export async function main(event: string): Promise<void> {
const id = input.session_id || 'default';
const s = readSession(dir, id);
s.lastQuery = prompt;
+ // Accumulate tokens saved this session (baseline − pack), so the statusline
+ // can show a running total. Guarded: only when `ask` returned a baseline.
+ const saved = retrievalTokensSaved(ask);
+ if (saved > 0) s.savedTokens = (s.savedTokens ?? 0) + saved;
const agent = input?.agent?.name;
if (agent) s.perAgentQuery[agent] = prompt;
writeSession(dir, id, s);
diff --git a/src/claude/state.ts b/src/claude/state.ts
index 41374554..363e14e4 100644
--- a/src/claude/state.ts
+++ b/src/claude/state.ts
@@ -11,6 +11,8 @@ export interface SessionState {
lastQuery: string | null;
perAgentQuery: Record<string, string>;
graftReads: number; sourceReads: number;
+ /** Cumulative tokens saved this session via `ask --source` retrieval (est.). */
+ savedTokens: number;
}
export const LOCK_STALE_MS = 300000;
@@ -20,7 +22,7 @@ export function emptyStats(): Stats {
staleCount: 0, dirty: false, syncing: false, syncedAt: null, lastFile: null };
}
function emptySession(): SessionState {
- return { lastQuery: null, perAgentQuery: {}, graftReads: 0, sourceReads: 0 };
+ return { lastQuery: null, perAgentQuery: {}, graftReads: 0, sourceReads: 0, savedTokens: 0 };
}
export function cacheDir(projectDir: string): string { return join(projectDir, 'graft', '.cache'); }
diff --git a/src/graph/extract.ts b/src/graph/extract.ts
index 029f06ed..ead49ba7 100644
--- a/src/graph/extract.ts
+++ b/src/graph/extract.ts
@@ -106,6 +106,7 @@ export function extractFile(rel: string, source: string, lang: Language): Extrac
exported: true,
origin: "ast",
body_hash: contentHash(source),
+ chars: source.length,
summary_state: "pending",
summary: null,
crux: null,
diff --git a/src/graph/types.ts b/src/graph/types.ts
index 39cc33db..fd17bfb9 100644
--- a/src/graph/types.ts
+++ b/src/graph/types.ts
@@ -47,6 +47,8 @@ export interface NodeV1 {
exported: boolean;
origin: "ast";
body_hash: string; // sha256 of the definition text; the Tier-2 re-run trigger
+ chars?: number; // byte length of the WHOLE file (file nodes only); the baseline
+ // `ask` uses to estimate tokens saved vs reading the file whole
// meaning (Tier-2, one LLM call)
summary_state: SummaryState;
diff --git a/test/claude-format.test.ts b/test/claude-format.test.ts
index 7d938b87..3366d1d1 100644
--- a/test/claude-format.test.ts
+++ b/test/claude-format.test.ts
@@ -68,11 +68,20 @@ test('formatRetrieval renders top hits, trims snippet, first pointer only', () =
{ kind: 'concept', title: 'PKCE', pointer: 'src/pkce.ts, src/client.ts', snippet: 'Validates the challenge.', score: 1 },
] } as any;
const txt = strip(formatRetrieval(ask)!);
- assert.match(txt, /relevant context/);
- assert.match(txt, /PKCE — src\/pkce\.ts — Validates the challenge\./);
+ assert.match(txt, /retrieved context/);
+ assert.match(txt, /PKCE — src\/pkce\.ts/);
+ assert.match(txt, /Validates the challenge\./); // snippet trimmed, own line
assert.doesNotMatch(txt, /client\.ts/); // only the first pointer segment
});
+test('formatRetrieval appends a tokens-saved line when ask reports a baseline', () => {
+ const ask = { query: 'pkce', mode: 'lexical', saved: { files: 1, baselineChars: 8000 }, hits: [
+ { kind: 'symbol', title: 'verify', pointer: 'src/pkce.ts:L1-L4', snippet: 's', score: 1, code: 'a\nb' },
+ ] } as any;
+ const txt = strip(formatRetrieval(ask)!);
+ assert.match(txt, /tokens saved ≈ [\d,]+ \(\d+%\)/);
+});
+
test('formatRetrieval returns null for no hits', () => {
assert.equal(formatRetrieval({ query: 'x', mode: 'empty', hits: [] } as any), null);
});
diff --git a/test/claude-state.test.ts b/test/claude-state.test.ts
index 397ff1f0..23e7607f 100644
--- a/test/claude-state.test.ts
+++ b/test/claude-state.test.ts
@@ -24,7 +24,7 @@ test('stats round-trip and patch merge', () => {
test('session defaults and round-trip', () => {
const d = fresh();
const s = readSession(d, 'abc');
- assert.deepEqual(s, { lastQuery: null, perAgentQuery: {}, graftReads: 0, sourceReads: 0 });
+ assert.deepEqual(s, { lastQuery: null, perAgentQuery: {}, graftReads: 0, sourceReads: 0, savedTokens: 0 });
s.lastQuery = 'pkce'; s.graftReads = 2;
writeSession(d, 'abc', s);
assert.equal(readSession(d, 'abc').lastQuery, 'pkce');