savemytokens 0.2.0

package/dist/adapters/codex/provider.js

@@ -0,0 +1,171 @@
+import path from "node:path";
+import { FIVE_HOUR_MS, WINDOW_MS, addSample, commitMeter, liveWindow, loadClaimants, loadMeter, loadQuota, openBuckets, saveQuota, scanNew, upsertClaimant, } from "../../runtime/kernel.mjs";
+import { codexAdapter } from "./index.js";
+export const ADAPTER_ID = "codex";
+const WINDOW_LABELS = {
+    five_hour: "5-hour window",
+    seven_day: "7-day window",
+    spend_limit: "spend limit",
+};
+function windowKeyFor(minutes) {
+    if (minutes <= 0)
+        return null;
+    return minutes <= 24 * 60 ? "five_hour" : "seven_day";
+}
+function readLimits(payload, into) {
+    for (const slot of ["primary", "secondary"]) {
+        const limit = payload?.rate_limits?.[slot];
+        if (!limit || typeof limit.used_percent !== "number")
+            continue;
+        const key = windowKeyFor(Number(limit.window_minutes ?? 0));
+        if (!key)
+            continue;
+        into[key] = { usedPercent: limit.used_percent, resetsAt: Number(limit.resets_at ?? 0) };
+    }
+}
+export function resourcesFor(now = Date.now()) {
+    const quota = loadQuota(ADAPTER_ID);
+    const keys = ["five_hour", "seven_day"];
+    return keys.map((key) => {
+        const window = liveWindow(quota, key, now);
+        return {
+            id: `${ADAPTER_ID}:${key}`,
+            adapter: ADAPTER_ID,
+            label: WINDOW_LABELS[key],
+            unit: "observed_usage",
+            window: { kind: "rolling", ms: WINDOW_MS[key] ?? FIVE_HOUR_MS, ...(window ? { resetsAt: window.resetsAt } : {}) },
+            capacity: window
+                ? { amount: 100, confidence: "published", asOf: quota?.at ?? now }
+                : { amount: 0, confidence: "unknown" },
+            usedPercent: window ? window.usedPercent : null,
+        };
+    });
+}
+export function sweep(since, now = Date.now()) {
+    if (!codexAdapter.detect())
+        return;
+    const known = new Map(loadClaimants(ADAPTER_ID).map((claimant) => [claimant.id, claimant]));
+    const windows = {};
+    let latestLimitAt = 0;
+    for (const ref of codexAdapter.discover({ since, project: null })) {
+        const id = path.basename(ref.file, ".jsonl");
+        const record = loadMeter(ADAPTER_ID, id);
+        const buckets = openBuckets(record);
+        const seen = new Set(record.seen);
+        const fresh = [];
+        scanNew(record, [ref.file], (line) => {
+            if (line.length < 2 || line.charCodeAt(0) !== 123)
+                return;
+            const wantsUsage = line.includes('"token_count"');
+            const wantsMeta = line.includes('"session_meta"');
+            const wantsPrompt = line.includes('"user_message"');
+            if (!wantsUsage && !wantsMeta && !wantsPrompt)
+                return;
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            const at = typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : NaN;
+            const stamp = Number.isFinite(at) ? at : now;
+            const payload = entry.payload ?? {};
+            if (entry.type === "session_meta" || payload.type === "session_meta") {
+                const cwd = payload.cwd ?? entry.payload?.payload?.cwd;
+                if (typeof cwd === "string" && !record.project)
+                    record.project = cwd;
+                return;
+            }
+            if (payload.type === "user_message") {
+                const text = typeof payload.message === "string" ? payload.message : "";
+                if (text && !text.startsWith("<"))
+                    record.prompt = text.replace(/\s+/g, " ").trim().slice(0, 120);
+                return;
+            }
+            if (payload.type !== "token_count")
+                return;
+            if (payload.rate_limits && stamp >= latestLimitAt) {
+                latestLimitAt = stamp;
+                readLimits(payload, windows);
+            }
+            const last = payload.info?.last_token_usage;
+            if (!last)
+                return;
+            const signature = `${stamp}:${last.input_tokens ?? 0}:${last.output_tokens ?? 0}:${last.cached_input_tokens ?? 0}`;
+            if (seen.has(signature))
+                return;
+            seen.add(signature);
+            fresh.push(signature);
+            const cached = last.cached_input_tokens ?? 0;
+            addSample(buckets, stamp, {
+                input: Math.max(0, (last.input_tokens ?? 0) - cached),
+                output: last.output_tokens ?? 0,
+                cacheWrite: 0,
+                cacheRead: cached,
+            });
+            if (stamp > record.lastAt)
+                record.lastAt = stamp;
+        });
+        commitMeter(ADAPTER_ID, id, record, buckets, fresh, now);
+        const existing = known.get(id);
+        const project = record.project || "";
+        upsertClaimant(ADAPTER_ID, id, {
+            project: existing?.project || project,
+            label: existing?.label || (project ? path.basename(project) : id.slice(-8)),
+            prompt: record.prompt || existing?.prompt || "",
+            ...(record.lastAt > 0 ? { lastSeen: record.lastAt } : {}),
+            ...(existing ? {} : { startedAt: record.buckets[0]?.[0] ?? now, state: "active" }),
+        });
+    }
+    if (Object.keys(windows).length > 0) {
+        const previous = loadQuota(ADAPTER_ID);
+        const reading = {
+            at: latestLimitAt || now,
+            source: "rollout",
+            windows,
+            ...(previous?.history ? { history: previous.history } : {}),
+        };
+        saveQuota(ADAPTER_ID, reading);
+    }
+}
+export const codexMeter = {
+    async sample(since, until = Date.now()) {
+        const out = [];
+        for (const claimant of loadClaimants(ADAPTER_ID)) {
+            const record = loadMeter(ADAPTER_ID, claimant.id);
+            for (const row of record.buckets) {
+                const at = row[0] ?? 0;
+                if (at < since || at > until)
+                    continue;
+                const input = row[1] ?? 0;
+                const output = row[2] ?? 0;
+                const cacheWrite = row[3] ?? 0;
+                const cacheRead = row[4] ?? 0;
+                const weighted = input + output * 5 + cacheWrite * 1.25 + cacheRead * 0.1;
+                out.push({
+                    claimantId: claimant.id,
+                    amount: weighted,
+                    at,
+                    metrics: { tokens: input + output + cacheWrite + cacheRead, weighted, requests: row[5] ?? 0 },
+                });
+            }
+        }
+        return out.sort((a, b) => a.at - b.at);
+    },
+};
+export const codexEnforcer = {
+    supports: [],
+    async apply(_claimant, level) {
+        return { applied: false, message: `Codex has no hook to inject through, so ${level} is not available.` };
+    },
+};
+export const codexProvider = {
+    id: ADAPTER_ID,
+    label: "Codex",
+    detect: () => codexAdapter.detect(),
+    resources: (now) => resourcesFor(now),
+    sweep,
+    meter: codexMeter,
+    enforcer: codexEnforcer,
+};

package/dist/adapters/index.js

@@ -0,0 +1,10 @@
+import { claudeCodeAdapter } from "./claude-code/index.js";
+import { codexAdapter } from "./codex/index.js";
+import { pendingAdapters } from "./pending.js";
+export const adapters = [claudeCodeAdapter, codexAdapter, ...pendingAdapters];
+export function activeAdapters() {
+    return adapters.filter((a) => a.supported && a.detect());
+}
+export function pendingDetected() {
+    return pendingAdapters.filter((a) => a.detect());
+}

package/dist/adapters/pending.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function pendingAdapter(id, label, dataDir, reason) {
+    return {
+        id,
+        label,
+        supported: false,
+        dataDir,
+        reason,
+        detect() {
+            try {
+                return fs.statSync(dataDir).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        },
+        discover() {
+            return [];
+        },
+        async parse() {
+            return null;
+        },
+    };
+}
+export const geminiAdapter = pendingAdapter("gemini", "Gemini CLI", path.join(os.homedir(), ".gemini"), "it logs prompts but no token counts, so there is nothing to measure");
+export const grokAdapter = pendingAdapter("grok", "Grok", path.join(os.homedir(), ".grok"), "its local store is a title/cwd search index with no token counts");
+export const pendingAdapters = [geminiAdapter, grokAdapter];

package/dist/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/analyze/aggregate.js

@@ -0,0 +1,180 @@
+import { usd } from "../core/pricing.js";
+import { addUsage, emptyUsage, rawTokens, weigh } from "../core/tokens.js";
+function merger() {
+    const map = new Map();
+    return {
+        add(key, weighted, count, chars, extra, combine) {
+            const existing = map.get(key);
+            if (!existing) {
+                map.set(key, { key, weighted, count, chars, sessions: 1, extra });
+                return;
+            }
+            existing.weighted += weighted;
+            existing.count += count;
+            existing.chars += chars;
+            existing.sessions += 1;
+            existing.extra = combine(existing.extra, extra);
+        },
+        top(limit) {
+            return [...map.values()].sort((a, b) => b.weighted - a.weighted).slice(0, limit);
+        },
+    };
+}
+export function aggregate(corpus) {
+    const usage = emptyUsage();
+    const models = new Map();
+    const reads = merger();
+    const outputs = merger();
+    const hooks = merger();
+    const writes = merger();
+    const failures = merger();
+    let tasks = 0;
+    let turns = 0;
+    let toolCalls = 0;
+    let bloatTurns = 0;
+    let bloatTokens = 0;
+    let bloatWeighted = 0;
+    let bloatSessions = 0;
+    let peakContext = 0;
+    let coldSessions = 0;
+    let coldWeighted = 0;
+    let apiErrors = 0;
+    let interruptions = 0;
+    let toolErrors = 0;
+    let sidechainTurns = 0;
+    let sidechainWeighted = 0;
+    let compactions = 0;
+    let searchChars = 0;
+    let rateLimitHits = 0;
+    let totalUsd = 0;
+    const allTasks = [];
+    const projects = new Map();
+    const outcomes = { completed: 0, interrupted: 0, failed: 0 };
+    for (const session of corpus.sessions) {
+        addUsage(usage, session.usage);
+        turns += session.turns;
+        toolCalls += session.toolCalls;
+        tasks += session.tasks.length;
+        apiErrors += session.apiErrors;
+        interruptions += session.interruptions;
+        toolErrors += session.toolErrors;
+        sidechainTurns += session.sidechainTurns;
+        sidechainWeighted += session.sidechainWeighted;
+        compactions += session.compactions;
+        searchChars += session.searchChars;
+        rateLimitHits += session.rateLimitHits ?? 0;
+        for (const task of session.tasks) {
+            allTasks.push(task);
+            totalUsd += task.usd;
+            const name = (task.project || session.project).split("/").pop() || "unknown";
+            const entry = projects.get(name) ?? { name, usd: 0, tasks: 0 };
+            entry.usd += task.usd;
+            entry.tasks += 1;
+            projects.set(name, entry);
+        }
+        bloatTurns += session.bloatTurns;
+        bloatTokens += session.bloatTokens;
+        bloatWeighted += session.bloatWeighted;
+        if (session.bloatTurns > 0)
+            bloatSessions++;
+        if (session.peakContext > peakContext)
+            peakContext = session.peakContext;
+        if (session.coldStart) {
+            coldSessions++;
+            coldWeighted += session.usage.cacheWrite * 1.25;
+        }
+        for (const task of session.tasks)
+            outcomes[task.outcome]++;
+        for (const model of session.models) {
+            let entry = models.get(model.model);
+            if (!entry) {
+                entry = { model: model.model, turns: 0, usage: emptyUsage(), weighted: 0, trivialTurns: 0, trivialWeighted: 0 };
+                models.set(model.model, entry);
+            }
+            entry.turns += model.turns;
+            addUsage(entry.usage, model.usage);
+            entry.weighted += model.weighted;
+            entry.trivialTurns += model.trivialTurns;
+            entry.trivialWeighted += model.trivialWeighted;
+        }
+        for (const read of session.reads) {
+            if (read.redundantReads === 0)
+                continue;
+            reads.add(read.path, read.redundantWeighted, read.reads, read.chars, { reads: read.reads, redundantReads: read.redundantReads, redundantChars: read.redundantChars }, (a, b) => ({
+                reads: a.reads + b.reads,
+                redundantReads: a.redundantReads + b.redundantReads,
+                redundantChars: a.redundantChars + b.redundantChars,
+            }));
+        }
+        for (const output of session.outputs) {
+            outputs.add(output.label, output.excessWeighted, output.calls, output.chars, { tool: output.tool, calls: output.calls, maxChars: output.maxChars, excessChars: output.excessChars }, (a, b) => ({
+                tool: a.tool,
+                calls: a.calls + b.calls,
+                maxChars: Math.max(a.maxChars, b.maxChars),
+                excessChars: a.excessChars + b.excessChars,
+            }));
+        }
+        for (const hook of session.hooks) {
+            if (hook.weighted <= 0)
+                continue;
+            hooks.add(hook.name, hook.weighted, hook.events, hook.chars, { events: hook.events, sample: hook.sample ?? "", command: hook.command ?? "" }, (x, y) => ({ events: x.events + y.events, sample: x.sample || y.sample, command: x.command || y.command }));
+        }
+        for (const write of session.writes) {
+            if (write.writes < 2)
+                continue;
+            writes.add(write.path, write.rewrittenWeighted, write.writes, write.rewrittenChars, { writes: write.writes, edits: write.edits, rewrittenChars: write.rewrittenChars }, (a, b) => ({
+                writes: a.writes + b.writes,
+                edits: a.edits + b.edits,
+                rewrittenChars: a.rewrittenChars + b.rewrittenChars,
+            }));
+        }
+        for (const failure of session.failures) {
+            failures.add(failure.label, failure.weighted, failure.failures, failure.chars, { tool: failure.tool, failures: failure.failures }, (a, b) => ({ tool: a.tool, failures: a.failures + b.failures }));
+        }
+    }
+    return {
+        totals: {
+            usage,
+            weighted: weigh(usage),
+            usd: totalUsd || usd("claude-opus-5", usage),
+            tokens: rawTokens(usage),
+            freshTokens: usage.input + usage.output + usage.cacheWrite,
+            cacheReadTokens: usage.cacheRead,
+            sessions: corpus.sessions.length,
+            tasks,
+            turns,
+            toolCalls,
+        },
+        models: [...models.values()].sort((a, b) => b.weighted - a.weighted),
+        reads: reads.top(12),
+        outputs: outputs.top(12),
+        hooks: hooks.top(12),
+        writes: writes.top(12),
+        failures: failures.top(12),
+        bloat: { turns: bloatTurns, tokens: bloatTokens, weighted: bloatWeighted, sessions: bloatSessions, peak: peakContext },
+        coldSessions,
+        coldWeighted,
+        apiErrors,
+        interruptions,
+        toolErrors,
+        sidechainTurns,
+        sidechainWeighted,
+        compactions,
+        outcomes,
+        searchChars,
+        rateLimitHits,
+        allTasks,
+        topTasks: allTasks.filter((t) => t.turns > 0).sort((a, b) => b.usd - a.usd).slice(0, 5),
+        deadCarry: (() => {
+            const dead = allTasks.filter((t) => t.carriedIsDead).sort((a, b) => b.carriedUsd - a.carriedUsd);
+            const tokens = dead.reduce((sum, t) => sum + t.carriedContext * t.turns, 0);
+            return {
+                tasks: dead.slice(0, 8),
+                usd: dead.reduce((sum, t) => sum + t.carriedUsd, 0),
+                weighted: tokens * 0.1,
+                tokens,
+            };
+        })(),
+        projects: [...projects.values()].sort((a, b) => b.usd - a.usd),
+    };
+}

package/dist/analyze/combine.js

@@ -0,0 +1,11 @@
+export const MAX_COMBINED_WASTE = 0.45;
+export const OVERLAP_DISCOUNT = 0.5;
+export function combinedWaste(findings) {
+    if (findings.length === 0)
+        return 0;
+    const sorted = [...findings].sort((a, b) => b.wasteRatio - a.wasteRatio);
+    const [first, ...rest] = sorted;
+    const head = first?.wasteRatio ?? 0;
+    const tail = rest.reduce((sum, f) => sum + f.wasteRatio, 0) * OVERLAP_DISCOUNT;
+    return Math.min(MAX_COMBINED_WASTE, head + tail);
+}

package/dist/analyze/detectors.js

@@ -0,0 +1,244 @@
+import { DEAD_CARRY_TOKENS } from "../adapters/claude-code/parse.js";
+import { bytes, compactNumber, money, plural, shortPath } from "../util/fmt.js";
+const MIN_RATIO = 0.004;
+const MIN_USD = 1;
+const RECOVERABLE_ROUNDTRIPS = 0.4;
+const MIN_TRIVIAL_TURNS = 20;
+function usdPerWeighted(agg) {
+    return agg.totals.weighted > 0 ? agg.totals.usd / agg.totals.weighted : 0;
+}
+function finding(agg, input) {
+    const total = agg.totals.weighted;
+    if (total <= 0)
+        return null;
+    const wasteRatio = input.wastedWeighted / total;
+    const wastedUsd = input.wastedWeighted * usdPerWeighted(agg);
+    if (wasteRatio < MIN_RATIO || wastedUsd < MIN_USD)
+        return null;
+    return { ...input, wasteRatio, wastedUsd };
+}
+function receipt(task, amount, note) {
+    const project = (task.project || "").split("/").pop() || "unknown";
+    return `${money(amount).padStart(5)}  ${project.padEnd(11).slice(0, 11)}  ${note.padEnd(18)}  "${task.prompt}"`;
+}
+const deadCarry = (agg) => {
+    const dead = agg.deadCarry;
+    if (dead.tasks.length === 0)
+        return null;
+    const count = agg.allTasks.filter((t) => t.carriedIsDead).length;
+    const worst = dead.tasks[0];
+    if (!worst)
+        return null;
+    return finding(agg, {
+        id: "dead-carry",
+        actor: "you",
+        title: "Finished work still riding along in context",
+        confidence: "measured",
+        effort: "habit",
+        wastedWeighted: dead.weighted,
+        measured: [
+            `${count} ${plural(count, "task")} started with more than ${compactNumber(DEAD_CARRY_TOKENS)} tokens of earlier work already in context`,
+            `none of them re-opened a single file from that earlier work, and their prompts named their own subject`,
+            `that context was re-read on every turn: ${compactNumber(dead.tokens)} tokens`,
+        ],
+        receipts: dead.tasks.slice(0, 3).map((t) => receipt(t, t.carriedUsd, `carried ${compactNumber(t.carriedContext)} × ${t.turns}t`)),
+        fix: `Press Ctrl+C and start a new session (or /clear) when the next thing you type is not about the last thing you did. ` +
+            `Those tasks paid to re-read finished work on every single turn and never once looked at it again.`,
+    });
+};
+const hookNoise = (agg) => {
+    if (agg.hooks.length === 0)
+        return null;
+    const wasted = agg.hooks.reduce((sum, h) => sum + h.weighted, 0);
+    const top = agg.hooks[0];
+    if (!top)
+        return null;
+    const events = agg.hooks.reduce((sum, h) => sum + h.extra.events, 0);
+    return finding(agg, {
+        id: "hook-noise",
+        actor: "you",
+        title: "Hook output injected into context",
+        confidence: "estimated",
+        effort: "one-time",
+        wastedWeighted: wasted,
+        measured: [
+            `${events} hook ${plural(events, "event")} printed ${bytes(agg.hooks.reduce((s, h) => s + h.chars, 0))} into context`,
+            `worst: ${top.key}, the same bytes repeated ${top.extra.events}×`,
+        ],
+        receipts: [
+            top.extra.command ? `hook command: ${top.extra.command}` : "",
+            top.extra.sample ? `every call pastes: ${top.extra.sample}…` : "",
+            "read that payload. If the model has no use for it, it is pure cost",
+        ].filter(Boolean),
+        fix: top.extra.command.includes("CLAUDE_PLUGIN_ROOT")
+            ? `That hook belongs to a plugin, not to your settings.json, so you cannot pipe it away there. Turn the plugin off in the enabledPlugins block of ~/.claude/settings.json, or raise it with the plugin author. Its plain-text stdout lands in the transcript and is re-read on every later turn.`
+            : `Hook stdout that is not structured JSON lands in the transcript, so every later turn re-reads it. If that payload is for your terminal rather than for the model, append \` >/dev/null\` to the ${top.key} hook command in ~/.claude/settings.json. Keep it if the model acts on it.`,
+        detail: agg.hooks.slice(0, 5).map((h) => `${h.key} · ${h.extra.events}× · ${bytes(h.chars)}`),
+    });
+};
+const repeatedReads = (agg) => {
+    if (agg.reads.length === 0)
+        return null;
+    const wasted = agg.reads.reduce((sum, r) => sum + r.weighted, 0);
+    const redundantReads = agg.reads.reduce((sum, r) => sum + r.extra.redundantReads, 0);
+    const redundantChars = agg.reads.reduce((sum, r) => sum + r.extra.redundantChars, 0);
+    const top = agg.reads[0];
+    if (!top || redundantReads === 0)
+        return null;
+    return finding(agg, {
+        id: "repeated-reads",
+        actor: "you",
+        title: "The same file sent again, unchanged",
+        confidence: "estimated",
+        effort: "one-time",
+        wastedWeighted: wasted,
+        measured: [
+            `${redundantReads} identical ${plural(redundantReads, "re-read")} across ${agg.reads.length} ${plural(agg.reads.length, "file")} (${bytes(redundantChars)})`,
+            `worst: ${shortPath(top.key)}, ${top.extra.redundantReads}× after the first read`,
+        ],
+        fix: `${shortPath(top.key)} was byte-identical every time it was re-sent. If subagents each read it, put it in CLAUDE.md instead. ` +
+            `that costs one cache write per session rather than one full copy per agent.`,
+        detail: agg.reads.slice(0, 5).map((r) => `${shortPath(r.key)} · ${r.extra.redundantReads}× · ${bytes(r.extra.redundantChars)}`),
+    });
+};
+const largeOutput = (agg) => {
+    if (agg.outputs.length === 0)
+        return null;
+    const wasted = agg.outputs.reduce((sum, o) => sum + o.weighted, 0);
+    const calls = agg.outputs.reduce((sum, o) => sum + o.extra.calls, 0);
+    const chars = agg.outputs.reduce((sum, o) => sum + o.chars, 0);
+    const top = agg.outputs[0];
+    if (!top)
+        return null;
+    const fixFor = (tool, label) => {
+        if (tool === "Read")
+            return `Ask for the line range you need instead of the whole file.`;
+        if (tool === "Grep" || tool === "Glob")
+            return `Match on file names only, or scope it to one directory.`;
+        if (tool === "Bash")
+            return `Pipe it down: \`${label} 2>&1 | tail -40\`, or write the log to a file and grep it.`;
+        if (tool === "TaskOutput" || tool === "Agent" || tool === "Workflow")
+            return `Ask the subagent for its conclusion, not its transcript. Delegating only pays off if the bulk stays out of your context.`;
+        if (tool === "WebFetch" || tool === "WebSearch")
+            return `Name the fact you need in the fetch prompt so the page comes back summarised.`;
+        return `Ask for a narrower result. The whole payload rides along for the rest of the session.`;
+    };
+    return finding(agg, {
+        id: "large-output",
+        actor: "claude",
+        title: "Oversized command output",
+        confidence: "estimated",
+        effort: "habit",
+        wastedWeighted: wasted,
+        measured: [
+            `${calls} tool ${plural(calls, "result")} over 10 KB returned ${bytes(chars)}`,
+            `worst: ${shortPath(top.key)}, ${top.extra.calls}×, largest ${bytes(top.extra.maxChars)}`,
+        ],
+        fix: `${shortPath(top.key)} put ${bytes(top.chars)} into context across ${top.extra.calls} ${plural(top.extra.calls, "run")}. ${fixFor(top.extra.tool, shortPath(top.key))}`,
+        detail: agg.outputs.slice(0, 5).map((o) => `${shortPath(o.key)} · ${o.extra.calls}× · ${bytes(o.chars)}`),
+    });
+};
+const failedTools = (agg) => {
+    if (agg.failures.length === 0)
+        return null;
+    const wasted = agg.failures.reduce((sum, f) => sum + f.weighted, 0);
+    const total = agg.failures.reduce((sum, f) => sum + f.extra.failures, 0);
+    const top = agg.failures[0];
+    if (!top || total === 0)
+        return null;
+    return finding(agg, {
+        id: "failed-tools",
+        actor: "you",
+        title: "Failed and interrupted commands",
+        confidence: "estimated",
+        effort: "habit",
+        wastedWeighted: wasted,
+        measured: [
+            `${total} failed tool ${plural(total, "call")} returned ${bytes(agg.failures.reduce((s, f) => s + f.chars, 0))} of error output`,
+            `worst: ${shortPath(top.key)}, failed ${top.extra.failures}×`,
+        ],
+        fix: `${shortPath(top.key)} failed ${top.extra.failures}×. Each failure paid for its error dump and then for the retry that read it. Get it green in a terminal once, or wrap it so the agent sees one line instead of a stack trace.`,
+        detail: agg.failures.slice(0, 5).map((f) => `${shortPath(f.key)} · ${f.extra.failures} ${plural(f.extra.failures, "failure")} · ${bytes(f.chars)}`),
+    });
+};
+const writeChurn = (agg) => {
+    if (agg.writes.length === 0)
+        return null;
+    const wasted = agg.writes.reduce((sum, w) => sum + w.weighted, 0);
+    const top = agg.writes[0];
+    if (!top)
+        return null;
+    return finding(agg, {
+        id: "write-churn",
+        actor: "claude",
+        title: "Files rewritten whole instead of edited",
+        confidence: "estimated",
+        effort: "habit",
+        wastedWeighted: wasted,
+        measured: [
+            `${agg.writes.length} ${plural(agg.writes.length, "file")} written end-to-end more than once (${bytes(agg.writes.reduce((s, w) => s + w.extra.rewrittenChars, 0))})`,
+            `worst: ${shortPath(top.key)}, ${top.extra.writes} full writes${top.extra.edits > 0 ? ` and ${top.extra.edits} edits` : ""}`,
+        ],
+        fix: `${shortPath(top.key)} was rewritten in full ${top.extra.writes}×. A full rewrite is billed as output tokens, the most expensive kind, 5× input. Ask for targeted edits once a file exists.`,
+        detail: agg.writes.slice(0, 5).map((w) => `${shortPath(w.key)} · ${w.extra.writes} writes · ${bytes(w.extra.rewrittenChars)}`),
+    });
+};
+const coldCache = (agg) => {
+    if (agg.coldSessions < 3)
+        return null;
+    return finding(agg, {
+        id: "cold-cache",
+        actor: "you",
+        title: "Sessions dropped before the cache paid off",
+        confidence: "measured",
+        effort: "habit",
+        wastedWeighted: agg.coldWeighted,
+        measured: [
+            `${agg.coldSessions} ${plural(agg.coldSessions, "session")} ended within three turns`,
+            `each paid a full cache write at 1.25× that was never read back at 0.1×`,
+        ],
+        fix: `Starting a session re-uploads your CLAUDE.md, tools and skills before anything useful happens. Keep quick questions in a session you already have open.`,
+    });
+};
+const highContextRoundTrips = (agg) => {
+    const premium = agg.models.filter((m) => m.trivialTurns > 0);
+    const trivialWeighted = premium.reduce((sum, m) => sum + m.trivialWeighted, 0);
+    const trivialTurns = premium.reduce((sum, m) => sum + m.trivialTurns, 0);
+    if (trivialTurns < MIN_TRIVIAL_TURNS)
+        return null;
+    const avgContext = trivialTurns > 0 ? Math.round(trivialWeighted / trivialTurns / 0.1) : 0;
+    return finding(agg, {
+        id: "roundtrips",
+        actor: "claude",
+        title: "Cheap actions taken at expensive context",
+        confidence: "estimated",
+        effort: "habit",
+        wastedWeighted: trivialWeighted * RECOVERABLE_ROUNDTRIPS,
+        measured: [
+            `${trivialTurns} ${plural(trivialTurns, "turn")} did nothing but run one command or read one file`,
+            `each still re-read the whole conversation, roughly ${compactNumber(avgContext)} tokens per turn`,
+        ],
+        fix: `This is not about the model being too good for the job. A cheap turn costs the same as a hard one because both re-read everything. ` +
+            `Cut the number of round trips: chain shell commands into one call, and hand multi-step digging to a subagent, which starts near-empty and returns only its answer.`,
+    });
+};
+export const detectors = [
+    deadCarry,
+    hookNoise,
+    repeatedReads,
+    largeOutput,
+    highContextRoundTrips,
+    failedTools,
+    writeChurn,
+    coldCache,
+];
+export function runDetectors(agg) {
+    const findings = [];
+    for (const detector of detectors) {
+        const result = detector(agg);
+        if (result)
+            findings.push(result);
+    }
+    const certainty = (f) => (f.confidence === "measured" ? 1 : 0.7);
+    return findings.sort((a, b) => b.wastedUsd * certainty(b) - a.wastedUsd * certainty(a));
+}

package/dist/analyze/index.js

@@ -0,0 +1,29 @@
+import { aggregate } from "./aggregate.js";
+import { combinedWaste } from "./combine.js";
+import { runDetectors } from "./detectors.js";
+import { scoreAudit } from "./score.js";
+export const AUDIT_VERSION = 1;
+export function analyze(corpus, ranAt = Date.now()) {
+    const agg = aggregate(corpus);
+    const findings = runDetectors(agg);
+    const wasteRatio = combinedWaste(findings);
+    const { score, breakdown } = scoreAudit(agg, wasteRatio);
+    const upliftRatio = wasteRatio > 0 ? 1 / (1 - wasteRatio) - 1 : 0;
+    return {
+        version: AUDIT_VERSION,
+        ranAt,
+        scope: corpus.scope,
+        totals: agg.totals,
+        findings,
+        score,
+        scoreBreakdown: breakdown,
+        wasteRatio,
+        upliftRatio,
+        models: agg.models,
+        outcomes: agg.outcomes,
+        rateLimitHits: agg.rateLimitHits,
+        topTasks: agg.topTasks,
+        projects: agg.projects,
+    };
+}
+export { aggregate } from "./aggregate.js";