costclaw 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# costclaw
+
+A local cost and setup audit for [Claude Code](https://claude.com/claude-code).
+Point it at your session logs and it shows where token spend leaks, scores your
+setup across six pillars, and ranks fixes by the dollars they recover.
+
+Your prompts never leave your machine. The audit parses the logs already on your
+disk and prints a report. It uploads nothing.
+
+## Use it
+
+Requires Node 20+.
+
+```bash
+npx costclaw audit
+```
+
+That reads `~/.claude/projects` (override with `--path <dir>`) and prints:
+
+```
+CostClaw audit
+Source: ~/.claude/projects (N sessions across M projects)
+
+Recoverable spend (cache-miss exposure): $XXX.XX
+
+Spend analyzed: $X,XXX.XX   Cache hit: 96.3%   Active hours: XXX.X
+Overall setup score: 91 / 100 (Dialed in)
+  CLAUDE.md quality      n/a
+  Context hygiene        [###################.] 95
+  Prompting patterns     [##################..] 92
+  Session management     [####################] 100
+  Tool and MCP config    [####################] 100
+  Cost discipline        [##############......] 70
+
+Top fixes by recoverable spend:
+  - [$XXX.XX] Recover spend lost to cache misses
+      Keep the start of each session stable so the prompt cache is reused.
+```
+
+## Options
+
+```
+costclaw audit [--path <dir>] [--claude-md <file>] [--json]
+```
+
+- `--path <dir>` audit a specific projects directory (default `~/.claude/projects`).
+- `--claude-md <file>` score a CLAUDE.md file's quality.
+- `--json` print the raw, derived `AuditRecord` instead of the human report.
+
+## Privacy
+
+The only thing the tool produces is a derived `AuditRecord`: totals and generated
+prose, no prompt text, no file paths, no secrets. A hosted dashboard is on the
+roadmap and would receive only that derived record, never your logs.

package/dist/index.js

@@ -0,0 +1,1275 @@
+#!/usr/bin/env node
+
+// src/audit-command.ts
+import { readFile as readFile2 } from "fs/promises";
+
+// ../../packages/engine/src/types.ts
+function emptyTotals() {
+  return { input_tokens: 0, output_tokens: 0, cache_creation_tokens: 0, cache_read_tokens: 0 };
+}
+
+// ../../packages/engine/src/pricing.ts
+var PRICING_SNAPSHOT_DATE = "2026-05-13";
+var PRICES_PER_MTOK = Object.freeze({
+  "claude-opus-4-7": { input: 15, output: 75, cache_write: 18.75, cache_read: 1.5 },
+  "claude-opus-4-7[1m]": { input: 15, output: 75, cache_write: 18.75, cache_read: 1.5 },
+  "claude-opus-4-6": { input: 15, output: 75, cache_write: 18.75, cache_read: 1.5 },
+  "claude-sonnet-4-6": { input: 3, output: 15, cache_write: 3.75, cache_read: 0.3 },
+  "claude-sonnet-4-5": { input: 3, output: 15, cache_write: 3.75, cache_read: 0.3 },
+  "claude-haiku-4-5": { input: 1, output: 5, cache_write: 1.25, cache_read: 0.1 },
+  "claude-haiku-4-5-20251001": { input: 1, output: 5, cache_write: 1.25, cache_read: 0.1 }
+});
+var FALLBACK = { input: 3, output: 15, cache_write: 3.75, cache_read: 0.3 };
+function priceFor(model) {
+  if (!model) return FALLBACK;
+  const exact = PRICES_PER_MTOK[model];
+  if (exact) return exact;
+  const noTag = model.replace(/\[[^\]]*\]$/, "");
+  if (PRICES_PER_MTOK[noTag]) return PRICES_PER_MTOK[noTag];
+  const noDate = noTag.replace(/-\d{8}$/, "");
+  if (PRICES_PER_MTOK[noDate]) return PRICES_PER_MTOK[noDate];
+  return FALLBACK;
+}
+var num = (v) => Number(v) || 0;
+function costForUsage(model, usage) {
+  const p = priceFor(model);
+  const i = num(usage?.input_tokens);
+  const o = num(usage?.output_tokens);
+  const cw = num(usage?.cache_creation_input_tokens);
+  const cr = num(usage?.cache_read_input_tokens);
+  return (i * p.input + o * p.output + cw * p.cache_write + cr * p.cache_read) / 1e6;
+}
+function cacheSavingsForUsage(model, usage) {
+  const p = priceFor(model);
+  const cr = num(usage?.cache_read_input_tokens);
+  return cr * (p.input - p.cache_read) / 1e6;
+}
+function cacheHitRate(totals) {
+  const denom = num(totals.input_tokens) + num(totals.cache_creation_tokens) + num(totals.cache_read_tokens);
+  if (!denom) return 0;
+  return num(totals.cache_read_tokens) / denom;
+}
+
+// ../../packages/engine/src/sanitize.ts
+function sanitizeText(input) {
+  let out = input;
+  out = out.replace(/[‘’‚‛]/g, "'");
+  out = out.replace(/[“”„‟]/g, '"');
+  out = out.replace(/…/g, "...");
+  out = out.replace(/(\d)\s*[—–]\s*(\d)/g, "$1-$2");
+  out = out.replace(/\s*[—–]\s*/g, ", ");
+  out = out.replace(/ +,/g, ",");
+  out = out.replace(/,\s*,/g, ",");
+  out = out.replace(/[ \t]{2,}/g, " ");
+  out = out.replace(/[ \t]+$/gm, "");
+  return out;
+}
+
+// ../../packages/engine/src/parser.ts
+function safeParse(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+function usageKey(rec, seq) {
+  const requestId = rec.requestId || rec.message?.requestId;
+  if (requestId) return `req:${requestId}`;
+  const messageId = rec.message?.id;
+  if (messageId) return `msg:${messageId}`;
+  if (rec.uuid) return `row:${rec.uuid}`;
+  return `row:#${seq}`;
+}
+function projectFromCwd(cwd) {
+  if (!cwd) return null;
+  const parts = cwd.split(/[\\/]+/).filter(Boolean);
+  return parts.length ? parts[parts.length - 1] : null;
+}
+function targetFor(name, input) {
+  const s = (v, n) => typeof v === "string" && v.length ? v.slice(0, n) : null;
+  if (["Read", "Edit", "Write", "NotebookEdit"].includes(name)) return s(input.file_path, 200);
+  if (["Grep", "Glob"].includes(name)) return s(input.path ?? input.glob ?? input.pattern, 160);
+  if (["Bash", "PowerShell"].includes(name)) {
+    const cmd = typeof input.command === "string" ? input.command.trim().split(/\s+/)[0] : null;
+    return cmd ? cmd.slice(0, 60) : null;
+  }
+  if (name.startsWith("Task")) return s(input.subject ?? input.description, 80);
+  if (["WebFetch", "WebSearch"].includes(name)) return s(input.url ?? input.query, 60);
+  if (name === "Agent") return s(input.subagent_type ?? input.description, 60);
+  return null;
+}
+var isToolUse = (b) => !!b && typeof b === "object" && b.type === "tool_use" && typeof b.name === "string";
+function extractTools(content) {
+  const names = [];
+  const events = [];
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (isToolUse(block)) {
+        const name = block.name;
+        const input = block.input ?? {};
+        names.push(name);
+        events.push({ name, target: targetFor(name, input) });
+      }
+    }
+  }
+  return { names, events };
+}
+function parseSession(text, opts = {}) {
+  const s = {
+    sessionUuid: null,
+    projectSlug: null,
+    startedAt: null,
+    endedAt: null,
+    durationMinutes: null,
+    modelPrimary: null,
+    jsonlRecords: 0,
+    assistantRecords: 0,
+    userRecords: 0,
+    fragmentsWithUsage: 0,
+    duplicateFragmentsSkipped: 0,
+    modelRequests: 0,
+    totals: emptyTotals(),
+    cost_usd: 0,
+    cache_savings_usd: 0,
+    toolUsage: {},
+    toolEvents: [],
+    skippedLines: 0
+  };
+  const seen = /* @__PURE__ */ new Set();
+  const modelCounts = /* @__PURE__ */ new Map();
+  let cwd = null;
+  let seq = 0;
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    const rec = safeParse(line);
+    if (!rec) {
+      s.skippedLines += 1;
+      continue;
+    }
+    s.jsonlRecords += 1;
+    if (rec.sessionId && s.sessionUuid === null) s.sessionUuid = rec.sessionId;
+    if (typeof rec.cwd === "string" && cwd === null) cwd = rec.cwd;
+    if (rec.timestamp) {
+      if (s.startedAt === null || rec.timestamp < s.startedAt) s.startedAt = rec.timestamp;
+      if (s.endedAt === null || rec.timestamp > s.endedAt) s.endedAt = rec.timestamp;
+    }
+    if (rec.type !== "user" && rec.type !== "assistant") continue;
+    if (rec.type === "user") s.userRecords += 1;
+    else s.assistantRecords += 1;
+    const model = rec.message?.model;
+    if (model) modelCounts.set(model, (modelCounts.get(model) ?? 0) + 1);
+    if (rec.type === "assistant") {
+      const { names, events } = extractTools(rec.message?.content);
+      for (const n of names) s.toolUsage[n] = (s.toolUsage[n] ?? 0) + 1;
+      const requestId = rec.requestId || rec.message?.requestId || null;
+      for (const e of events) s.toolEvents.push({ name: e.name, requestId, target: e.target });
+      const usage = rec.message?.usage;
+      if (usage) {
+        seq += 1;
+        const key = usageKey(rec, seq);
+        if (seen.has(key)) {
+          s.duplicateFragmentsSkipped += 1;
+          continue;
+        }
+        seen.add(key);
+        s.fragmentsWithUsage += 1;
+        s.modelRequests += 1;
+        s.totals.input_tokens += Number(usage.input_tokens) || 0;
+        s.totals.output_tokens += Number(usage.output_tokens) || 0;
+        s.totals.cache_creation_tokens += Number(usage.cache_creation_input_tokens) || 0;
+        s.totals.cache_read_tokens += Number(usage.cache_read_input_tokens) || 0;
+        s.cost_usd += costForUsage(model, usage);
+        s.cache_savings_usd += cacheSavingsForUsage(model, usage);
+      }
+    }
+  }
+  s.projectSlug = opts.projectSlug ?? projectFromCwd(cwd);
+  let best = null;
+  let bestCount = 0;
+  for (const [m, c] of modelCounts) if (c > bestCount) {
+    best = m;
+    bestCount = c;
+  }
+  s.modelPrimary = best;
+  if (s.startedAt && s.endedAt) {
+    const ms = Date.parse(s.endedAt) - Date.parse(s.startedAt);
+    s.durationMinutes = Number.isNaN(ms) ? null : ms / 6e4;
+  }
+  return s;
+}
+
+// ../../packages/engine/src/aggregate.ts
+function addTotals(into, from) {
+  into.input_tokens += from.input_tokens;
+  into.output_tokens += from.output_tokens;
+  into.cache_creation_tokens += from.cache_creation_tokens;
+  into.cache_read_tokens += from.cache_read_tokens;
+}
+function mostFrequent(values) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const v of values) if (v) counts.set(v, (counts.get(v) ?? 0) + 1);
+  let best = null;
+  let bestCount = 0;
+  for (const [v, c] of counts) if (c > bestCount) {
+    best = v;
+    bestCount = c;
+  }
+  return best;
+}
+function buildProjects(sessions) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const s of sessions) {
+    const slug = s.projectSlug || "uploaded";
+    const list = groups.get(slug) ?? [];
+    list.push(s);
+    groups.set(slug, list);
+  }
+  const projects = [];
+  for (const [slug, list] of groups) {
+    const totals = emptyTotals();
+    let cost = 0;
+    let savings = 0;
+    for (const s of list) {
+      addTotals(totals, s.totals);
+      cost += s.cost_usd;
+      savings += s.cache_savings_usd;
+    }
+    const sorted = [...list].sort((a, b) => b.cost_usd - a.cost_usd);
+    projects.push({
+      slug,
+      sessions: sorted,
+      sessionsCount: list.length,
+      totals,
+      cost_usd: cost,
+      cache_savings_usd: savings,
+      cacheHitRate: cacheHitRate(totals),
+      modelPrimary: mostFrequent(list.map((s) => s.modelPrimary))
+    });
+  }
+  return projects.sort((a, b) => b.cost_usd - a.cost_usd);
+}
+function buildSummary(projects) {
+  const totals = emptyTotals();
+  const modelBreakdown = {};
+  let cost = 0;
+  let savings = 0;
+  let sessionsCount = 0;
+  let durationHours = 0;
+  for (const p of projects) {
+    addTotals(totals, p.totals);
+    cost += p.cost_usd;
+    savings += p.cache_savings_usd;
+    sessionsCount += p.sessionsCount;
+    for (const s of p.sessions) {
+      const key = s.modelPrimary || "unknown";
+      modelBreakdown[key] = (modelBreakdown[key] ?? 0) + s.cost_usd;
+      if (s.durationMinutes && s.durationMinutes > 0) durationHours += s.durationMinutes / 60;
+    }
+  }
+  return {
+    projectsCount: projects.length,
+    sessionsCount,
+    cost_usd: cost,
+    cache_savings_usd: savings,
+    totals,
+    modelBreakdown,
+    cacheHitRate: cacheHitRate(totals),
+    durationHours
+  };
+}
+
+// ../../packages/engine/src/optimizer.ts
+var HIT_FLOOR = 0.5;
+var STREAK = 3;
+var HOT_PROJECT_SHARE = 0.6;
+var HEAVY_TOOL_FIRES = 100;
+var SHORT_SESSION_MAX_MINUTES = 10;
+var SHORT_SESSION_MIN_COST = 5;
+function severityForSavings(savings) {
+  if (savings >= 50) return "critical";
+  if (savings >= 10) return "warn";
+  return "info";
+}
+function ruleBadCacheHit(ctx) {
+  const out = [];
+  for (const proj of ctx.projects) {
+    const sorted = [...proj.sessions].sort((a, b) => (a.startedAt || "").localeCompare(b.startedAt || ""));
+    if (sorted.length < STREAK) continue;
+    const tail = sorted.slice(-STREAK);
+    if (!tail.every((s) => cacheHitRate(s.totals) < HIT_FLOOR)) continue;
+    const last = tail[tail.length - 1];
+    if (!last) continue;
+    const p = priceFor(proj.modelPrimary);
+    let savings = 0;
+    for (const s of tail) {
+      savings += (s.totals.cache_creation_tokens + s.totals.input_tokens) * (p.input - p.cache_read) / 1e6;
+    }
+    out.push({
+      ruleId: "BAD_CACHE_HIT",
+      severity: severityForSavings(savings),
+      project: proj.slug,
+      title: "Low cache hit rate across recent sessions",
+      description: `The last ${tail.length} sessions in ${proj.slug} reused little from the prompt cache, so input tokens were re-paid at full price.`,
+      suggestedAction: "Stabilize the start of each session (steady CLAUDE.md, consistent first reads) so the prompt cache is reused.",
+      estimatedMonthlySavingsUsd: savings,
+      evidence: { sessionsConsidered: tail.length, recentHitRate: cacheHitRate(last.totals) }
+    });
+  }
+  return out;
+}
+function ruleHotProject(ctx) {
+  const out = [];
+  if (ctx.summary.cost_usd <= 0) return out;
+  for (const proj of ctx.projects) {
+    const share = proj.cost_usd / ctx.summary.cost_usd;
+    if (share < HOT_PROJECT_SHARE) continue;
+    out.push({
+      ruleId: "HOT_PROJECT",
+      severity: "info",
+      project: proj.slug,
+      title: "One project dominates your spend",
+      description: `${proj.slug} accounts for ${Math.round(share * 100)}% of total spend.`,
+      suggestedAction: "Focus optimization effort here first; it is where savings compound.",
+      estimatedMonthlySavingsUsd: 0,
+      evidence: { share, projectCost: proj.cost_usd, totalCost: ctx.summary.cost_usd }
+    });
+  }
+  return out;
+}
+function ruleHeavyToolLoops(ctx) {
+  const out = [];
+  for (const proj of ctx.projects) {
+    for (const s of proj.sessions) {
+      for (const [tool, fires] of Object.entries(s.toolUsage)) {
+        if (fires < HEAVY_TOOL_FIRES) continue;
+        out.push({
+          ruleId: "HEAVY_TOOL_LOOPS",
+          severity: "warn",
+          project: proj.slug,
+          title: `Heavy ${tool} usage in one session`,
+          description: `${tool} fired ${fires} times in a single session, a sign of a stuck loop or unscoped search.`,
+          suggestedAction: `Add a guard or narrow the task so ${tool} is not called in a loop.`,
+          estimatedMonthlySavingsUsd: 0,
+          evidence: { tool, fires, sessionUuid: s.sessionUuid }
+        });
+      }
+    }
+  }
+  return out;
+}
+function ruleShortSessionBloat(ctx) {
+  const out = [];
+  for (const proj of ctx.projects) {
+    for (const s of proj.sessions) {
+      if (s.durationMinutes == null) continue;
+      if (s.durationMinutes >= SHORT_SESSION_MAX_MINUTES) continue;
+      if (s.cost_usd < SHORT_SESSION_MIN_COST) continue;
+      out.push({
+        ruleId: "SHORT_SESSION_BLOAT",
+        severity: "warn",
+        project: proj.slug,
+        title: "Expensive short session",
+        description: `A ${s.durationMinutes.toFixed(1)}-minute session cost $${s.cost_usd.toFixed(2)}, a sign of a bloated context for a small task.`,
+        suggestedAction: "Start a fresh, tightly scoped session for short tasks instead of carrying a large context.",
+        estimatedMonthlySavingsUsd: 0,
+        evidence: { minutes: s.durationMinutes, cost: s.cost_usd, sessionUuid: s.sessionUuid }
+      });
+    }
+  }
+  return out;
+}
+var RULES = [
+  { id: "BAD_CACHE_HIT", run: ruleBadCacheHit },
+  { id: "HOT_PROJECT", run: ruleHotProject },
+  { id: "HEAVY_TOOL_LOOPS", run: ruleHeavyToolLoops },
+  { id: "SHORT_SESSION_BLOAT", run: ruleShortSessionBloat }
+];
+function runOptimizer(ctx) {
+  const findings = [];
+  for (const rule of RULES) {
+    try {
+      findings.push(...rule.run(ctx));
+    } catch (err) {
+      findings.push({
+        ruleId: "RULE_ERROR",
+        severity: "info",
+        project: null,
+        title: `Rule ${rule.id} failed`,
+        description: err instanceof Error ? err.message : String(err),
+        suggestedAction: null,
+        estimatedMonthlySavingsUsd: 0,
+        evidence: null
+      });
+    }
+  }
+  return findings;
+}
+
+// ../../packages/engine/src/report.ts
+function analyzeUploads(files) {
+  const sessions = files.map((f) => parseSession(f.text, { projectSlug: null }));
+  const projects = buildProjects(sessions);
+  const summary = buildSummary(projects);
+  const findings = runOptimizer({ projects, summary });
+  return { summary, projects, findings };
+}
+function cacheMissExposureUsd(report) {
+  let total = 0;
+  for (const proj of report.projects) {
+    const p = priceFor(proj.modelPrimary);
+    total += (proj.totals.input_tokens + proj.totals.cache_creation_tokens) * (p.input - p.cache_read) / 1e6;
+  }
+  return total;
+}
+
+// ../../packages/engine/src/claudemd.ts
+function lerp(x, x0, x1, y0, y1) {
+  if (x1 === x0) return y0;
+  const t = (x - x0) / (x1 - x0);
+  return y0 + t * (y1 - y0);
+}
+function clamp(n, lo = 0, hi = 100) {
+  return Math.max(lo, Math.min(hi, n));
+}
+function scoreSize(chars) {
+  if (chars < 300) return clamp(lerp(chars, 0, 300, 20, 50));
+  if (chars < 800) return clamp(lerp(chars, 300, 800, 50, 85));
+  if (chars <= 6e3) return 100;
+  if (chars <= 12e3) return clamp(lerp(chars, 6e3, 12e3, 100, 70));
+  if (chars <= 2e4) return clamp(lerp(chars, 12e3, 2e4, 70, 40));
+  return 25;
+}
+function scoreStructure(chars, headings, bullets) {
+  if (chars < 200) return 60;
+  let score = 40;
+  if (headings >= 1) score += 20;
+  if (headings >= 3) score += 15;
+  if (bullets >= 3) score += 15;
+  if (chars > 1500 && headings === 0) score = Math.min(score, 35);
+  if (chars > 4e3 && headings < 3) score = Math.min(score, 55);
+  return clamp(score);
+}
+function scoreStability(chars, volatileMarkers) {
+  if (chars === 0) return 0;
+  const per1k = volatileMarkers / chars * 1e3;
+  return clamp(100 - per1k * 28);
+}
+function analyzeClaudeMd(text) {
+  const raw = (text ?? "").trim();
+  if (!raw) {
+    return {
+      present: false,
+      chars: 0,
+      estTokens: 0,
+      headings: 0,
+      bullets: 0,
+      volatileMarkers: 0,
+      sizeScore: null,
+      structureScore: null,
+      stabilityScore: null
+    };
+  }
+  const chars = raw.length;
+  const estTokens = Math.round(chars / 4);
+  const headings = (raw.match(/^#{1,6}\s/gm) || []).length;
+  const bullets = (raw.match(/^\s*[-*]\s/gm) || []).length;
+  const dateMarkers = (raw.match(/\b\d{4}-\d{2}-\d{2}\b/g) || []).length;
+  const wordMarkers = (raw.match(/\b(updated|last update|as of|changelog|todo|fixme|wip|in progress|currently)\b/gi) || []).length;
+  const volatileMarkers = dateMarkers + wordMarkers;
+  return {
+    present: true,
+    chars,
+    estTokens,
+    headings,
+    bullets,
+    volatileMarkers,
+    sizeScore: scoreSize(chars),
+    structureScore: scoreStructure(chars, headings, bullets),
+    stabilityScore: scoreStability(chars, volatileMarkers)
+  };
+}
+
+// ../../packages/engine/src/rubric.ts
+var PILLARS = {
+  claude_md: {
+    id: "claude_md",
+    name: "CLAUDE.md quality",
+    weight: 0.18,
+    description: "Whether your project memory is the right size, well structured, and cache stable.",
+    color: "#2DD4A8"
+  },
+  context_hygiene: {
+    id: "context_hygiene",
+    name: "Context hygiene",
+    weight: 0.2,
+    description: "How much of your context is served from cache versus reprocessed every turn.",
+    color: "#34D399"
+  },
+  prompting: {
+    id: "prompting",
+    name: "Prompting patterns",
+    weight: 0.15,
+    description: "Whether you plan before acting and give the agent a way to verify its own work.",
+    color: "#60A5FA"
+  },
+  session_mgmt: {
+    id: "session_mgmt",
+    name: "Session management",
+    weight: 0.15,
+    description: "How well sessions are scoped so cost per session and per minute stays sane.",
+    color: "#F59E0B"
+  },
+  tooling: {
+    id: "tooling",
+    name: "Tool and MCP config",
+    weight: 0.14,
+    description: "Whether tools, MCP servers, and permissions are scoped instead of bloating context.",
+    color: "#A855F7"
+  },
+  cost_discipline: {
+    id: "cost_discipline",
+    name: "Cost discipline",
+    weight: 0.18,
+    description: "Whether spend is watched and the model is matched to the task.",
+    color: "#F472B6"
+  }
+};
+var PILLAR_ORDER = [
+  "claude_md",
+  "context_hygiene",
+  "prompting",
+  "session_mgmt",
+  "tooling",
+  "cost_discipline"
+];
+var GAP_THRESHOLD = 60;
+var BANDS = [
+  { id: "critical", label: "Burning tokens", description: "Setup is leaking time and money on most turns. The fixes below are high leverage." },
+  { id: "leaky", label: "Leaky", description: "A working setup with clear, recoverable waste. A few changes pay for themselves." },
+  { id: "solid", label: "Solid", description: "A sound setup with some rough edges left to tighten." },
+  { id: "tight", label: "Tight", description: "A well-run setup. The remaining fixes are marginal." },
+  { id: "dialed", label: "Dialed in", description: "Close to the efficient frontier for your workload. Little left to recover." }
+];
+function bandFor(score) {
+  if (score < 40) return BANDS[0];
+  if (score < 60) return BANDS[1];
+  if (score < 75) return BANDS[2];
+  if (score < 90) return BANDS[3];
+  return BANDS[4];
+}
+var QUESTIONNAIRE = [
+  {
+    id: "cmd_scope",
+    pillar: "claude_md",
+    prompt: "Your CLAUDE.md mostly contains:",
+    options: [
+      { id: "stable", label: "Stable project facts and conventions", score: 100 },
+      { id: "mixed", label: "A mix of conventions and notes", score: 60 },
+      { id: "churny", label: "Lots of changing notes, logs, or TODOs", score: 25 },
+      { id: "none", label: "I do not have a CLAUDE.md", score: 0 }
+    ]
+  },
+  {
+    id: "clear_between",
+    pillar: "context_hygiene",
+    prompt: "Between unrelated tasks, do you clear or compact the context?",
+    options: [
+      { id: "always", label: "Usually or always", score: 100 },
+      { id: "sometimes", label: "Sometimes", score: 55 },
+      { id: "never", label: "Rarely or never", score: 10 }
+    ]
+  },
+  {
+    id: "plan_first",
+    pillar: "prompting",
+    prompt: "For multi-step tasks, do you plan or write a short spec before coding?",
+    options: [
+      { id: "usually", label: "Usually", score: 100 },
+      { id: "sometimes", label: "Sometimes", score: 55 },
+      { id: "rarely", label: "Rarely", score: 15 }
+    ]
+  },
+  {
+    id: "success_criteria",
+    pillar: "prompting",
+    prompt: "Do you give the agent success criteria or tests so it can verify its own work?",
+    options: [
+      { id: "usually", label: "Usually", score: 100 },
+      { id: "sometimes", label: "Sometimes", score: 60 },
+      { id: "rarely", label: "Rarely", score: 20 }
+    ]
+  },
+  {
+    id: "session_scope",
+    pillar: "session_mgmt",
+    prompt: "How do you scope your sessions?",
+    options: [
+      { id: "one_task", label: "One task per session, then reset", score: 100 },
+      { id: "loose", label: "Loosely, a few tasks per session", score: 55 },
+      { id: "marathon", label: "One long-running session", score: 20 }
+    ]
+  },
+  {
+    id: "mcp_scoped",
+    pillar: "tooling",
+    prompt: "How are your MCP servers and custom tools configured?",
+    options: [
+      { id: "minimal", label: "Minimal and scoped to what I use", score: 100 },
+      { id: "few", label: "A few, mostly used", score: 70 },
+      { id: "many", label: "Many, some unused and always loaded", score: 25 },
+      { id: "unsure", label: "Not sure", score: 40 }
+    ]
+  },
+  {
+    id: "permission_allowlist",
+    pillar: "tooling",
+    prompt: "Do you use a permission allowlist or settings to cut approval prompts?",
+    options: [
+      { id: "yes", label: "Yes", score: 100 },
+      { id: "partial", label: "Partly", score: 60 },
+      { id: "no", label: "No", score: 25 }
+    ]
+  },
+  {
+    id: "cost_monitor",
+    pillar: "cost_discipline",
+    prompt: "Do you track token spend or set a budget?",
+    options: [
+      { id: "active", label: "I actively monitor it", score: 100 },
+      { id: "glance", label: "I glance at the billing page", score: 55 },
+      { id: "never", label: "I do not track it", score: 15 }
+    ]
+  },
+  {
+    id: "model_choice",
+    pillar: "cost_discipline",
+    prompt: "Do you match the model to the task?",
+    options: [
+      { id: "match", label: "I use a cheaper model for routine work", score: 100 },
+      { id: "sometimes", label: "Sometimes", score: 60 },
+      { id: "top", label: "I run the top model for everything", score: 30 }
+    ]
+  }
+];
+function questionById(id) {
+  return QUESTIONNAIRE.find((q) => q.id === id);
+}
+function optionScore(question, optionId) {
+  if (!optionId) return null;
+  const opt = question.options.find((o) => o.id === optionId);
+  return opt ? opt.score : null;
+}
+
+// ../../packages/engine/src/scoring.ts
+function clamp2(n, lo = 0, hi = 100) {
+  return Math.max(lo, Math.min(hi, n));
+}
+function makeCheck(id, pillar, label, score, basis, signal) {
+  const assessed = score !== null;
+  return {
+    id,
+    pillar,
+    label,
+    assessed,
+    score: assessed ? Math.round(score) : null,
+    basis,
+    signal,
+    gap: assessed && score < GAP_THRESHOLD
+  };
+}
+function questionnaireCheck(id, label, answers) {
+  const q = questionById(id);
+  if (!q) return makeCheck(id, "claude_md", label, null, "Unknown question.", "questionnaire");
+  const score = optionScore(q, answers[id]);
+  const chosen = q.options.find((o) => o.id === answers[id]);
+  const basis = chosen ? `You answered: "${chosen.label}."` : "Not answered.";
+  return makeCheck(id, q.pillar, label, score, basis, "questionnaire");
+}
+function aggregateTools(report) {
+  let total = 0;
+  let bash = 0;
+  for (const p of report.projects) {
+    for (const s of p.sessions) {
+      for (const [tool, n] of Object.entries(s.toolUsage)) {
+        total += n;
+        if (tool === "Bash") bash += n;
+      }
+    }
+  }
+  return { total, bash };
+}
+function hasAnyDuration(report) {
+  for (const p of report.projects) {
+    for (const s of p.sessions) {
+      if (s.durationMinutes != null) return true;
+    }
+  }
+  return false;
+}
+function buildChecks(report, cmd, answers) {
+  const checks = [];
+  const s = report.summary;
+  checks.push(
+    makeCheck(
+      "cmd_size",
+      "claude_md",
+      "Size",
+      cmd.present ? cmd.sizeScore : null,
+      cmd.present ? `Your CLAUDE.md is ${cmd.chars.toLocaleString()} characters, about ${cmd.estTokens.toLocaleString()} tokens loaded on every turn.` : "No CLAUDE.md was uploaded.",
+      "claudemd"
+    )
+  );
+  checks.push(
+    makeCheck(
+      "cmd_structure",
+      "claude_md",
+      "Structure",
+      cmd.present ? cmd.structureScore : null,
+      cmd.present ? `${cmd.headings} heading${cmd.headings === 1 ? "" : "s"} and ${cmd.bullets} bullet point${cmd.bullets === 1 ? "" : "s"} across ${cmd.chars.toLocaleString()} characters.` : "No CLAUDE.md was uploaded.",
+      "claudemd"
+    )
+  );
+  checks.push(
+    makeCheck(
+      "cmd_stability",
+      "claude_md",
+      "Cache stability",
+      cmd.present ? cmd.stabilityScore : null,
+      cmd.present ? `${cmd.volatileMarkers} volatile marker${cmd.volatileMarkers === 1 ? "" : "s"} (dates, TODOs, "updated" notes) that change between sessions and reset the cache.` : "No CLAUDE.md was uploaded.",
+      "claudemd"
+    )
+  );
+  checks.push(questionnaireCheck("cmd_scope", "Content scope", answers));
+  const contextTokens = s.totals.input_tokens + s.totals.cache_creation_tokens + s.totals.cache_read_tokens;
+  checks.push(
+    makeCheck(
+      "cache_hit",
+      "context_hygiene",
+      "Cache hit rate",
+      contextTokens > 0 ? clamp2(s.cacheHitRate * 100) : null,
+      contextTokens > 0 ? `Your overall cache hit rate is ${(s.cacheHitRate * 100).toFixed(1)}% across ${s.sessionsCount} session${s.sessionsCount === 1 ? "" : "s"}.` : "No token usage was found in the logs.",
+      "metrics"
+    )
+  );
+  const cc = s.totals.cache_creation_tokens;
+  const cr = s.totals.cache_read_tokens;
+  const churnAssessable = cc + cr > 0;
+  const churnRatio = churnAssessable ? cc / (cc + cr) : 0;
+  const writesPerRead = cr > 0 ? cc / cr : cc > 0 ? Infinity : 0;
+  checks.push(
+    makeCheck(
+      "cache_churn",
+      "context_hygiene",
+      "Cache churn",
+      churnAssessable ? clamp2(100 - churnRatio * 200) : null,
+      churnAssessable ? `You wrote ${writesPerRead === Infinity ? "cache with no reads at all" : writesPerRead.toFixed(2) + " cache tokens for every one read"}; healthy caching reads far more than it writes.` : "No cache token usage was found.",
+      "metrics"
+    )
+  );
+  checks.push(questionnaireCheck("clear_between", "Clearing between tasks", answers));
+  checks.push(questionnaireCheck("plan_first", "Planning first", answers));
+  checks.push(questionnaireCheck("success_criteria", "Self-verification", answers));
+  const heavyLoops = report.findings.filter((f) => f.ruleId === "HEAVY_TOOL_LOOPS");
+  const thrashSessions = new Set(
+    heavyLoops.map((f) => f.evidence?.["sessionUuid"]).filter((v) => typeof v === "string")
+  ).size;
+  const thrashShare = s.sessionsCount > 0 ? thrashSessions / s.sessionsCount : 0;
+  const thrashPct = Math.round(thrashShare * 100);
+  checks.push(
+    makeCheck(
+      "tool_thrash",
+      "prompting",
+      "Tool looping",
+      s.sessionsCount > 0 ? clamp2(100 - thrashShare * 180) : null,
+      s.sessionsCount === 0 ? "No sessions to assess." : thrashSessions === 0 ? "No single tool fired 100 or more times in a session." : `${thrashSessions} of ${s.sessionsCount} sessions (${thrashPct}%) fired one tool 100 or more times.`,
+      "metrics"
+    )
+  );
+  const shortBloat = report.findings.filter((f) => f.ruleId === "SHORT_SESSION_BLOAT");
+  const durations = hasAnyDuration(report);
+  const bloatSessions = new Set(
+    shortBloat.map((f) => f.evidence?.["sessionUuid"]).filter((v) => typeof v === "string")
+  ).size;
+  const bloatShare = s.sessionsCount > 0 ? bloatSessions / s.sessionsCount : 0;
+  const bloatPct = Math.round(bloatShare * 100);
+  checks.push(
+    makeCheck(
+      "short_session_bloat",
+      "session_mgmt",
+      "Cost per minute",
+      durations && s.sessionsCount > 0 ? clamp2(100 - bloatShare * 180) : null,
+      !durations ? "Sessions had no usable timestamps to measure duration." : bloatSessions === 0 ? "No short session burned an outsized amount for its length." : `${bloatSessions} of ${s.sessionsCount} sessions (${bloatPct}%) cost over $5 in under 10 minutes.`,
+      "metrics"
+    )
+  );
+  checks.push(questionnaireCheck("session_scope", "Session scoping", answers));
+  checks.push(questionnaireCheck("mcp_scoped", "MCP and tool scope", answers));
+  checks.push(questionnaireCheck("permission_allowlist", "Permission allowlist", answers));
+  const tools = aggregateTools(report);
+  const bashShare = tools.total > 0 ? tools.bash / tools.total : 0;
+  checks.push(
+    makeCheck(
+      "bash_reliance",
+      "tooling",
+      "Tool fit",
+      tools.total >= 20 ? clamp2(100 - Math.max(0, bashShare - 0.3) * 200) : null,
+      tools.total >= 20 ? `Bash was ${(bashShare * 100).toFixed(0)}% of your ${tools.total.toLocaleString()} tool calls; dedicated tools like Grep, Glob, and Read are cheaper and cleaner than shelling out.` : "Too few tool calls to judge tool fit.",
+      "metrics"
+    )
+  );
+  const exposure = cacheMissExposureUsd(report);
+  const spend = s.cost_usd;
+  const exposureShare = spend > 0 ? exposure / spend : 0;
+  checks.push(
+    makeCheck(
+      "recoverable_exposure",
+      "cost_discipline",
+      "Recoverable spend",
+      spend > 0 ? clamp2(100 - exposureShare * 120) : null,
+      spend > 0 ? `$${exposure.toFixed(2)} of your $${spend.toFixed(2)} spend is cache-miss exposure that a stable prefix could largely recover.` : "No spend was found in the logs.",
+      "metrics"
+    )
+  );
+  checks.push(questionnaireCheck("cost_monitor", "Spend monitoring", answers));
+  checks.push(questionnaireCheck("model_choice", "Model fit", answers));
+  return checks;
+}
+function scorePillars(report, cmd, answers) {
+  const checks = buildChecks(report, cmd, answers);
+  const pillars = PILLAR_ORDER.map((id) => {
+    const cfg = PILLARS[id];
+    const pillarChecks = checks.filter((c) => c.pillar === id);
+    const assessedChecks = pillarChecks.filter((c) => c.assessed);
+    const assessed = assessedChecks.length > 0;
+    const score = assessed ? Math.round(assessedChecks.reduce((sum, c) => sum + c.score, 0) / assessedChecks.length) : null;
+    return { id, name: cfg.name, weight: cfg.weight, assessed, score, checks: pillarChecks };
+  });
+  let weighted = 0;
+  let weightSum = 0;
+  for (const p of pillars) {
+    if (p.assessed && p.score != null) {
+      weighted += p.score * p.weight;
+      weightSum += p.weight;
+    }
+  }
+  const overall = weightSum > 0 ? Math.round(weighted / weightSum) : 0;
+  return { pillars, overall, band: bandFor(overall) };
+}
+
+// ../../packages/engine/src/synthesize.ts
+var CHECK_FIX = {
+  cmd_structure: {
+    title: "Give CLAUDE.md clear structure",
+    action: "Break the file into sections with headings and short bulleted rules so the agent finds the right guidance fast instead of scanning a wall of text."
+  },
+  cmd_stability: {
+    title: "Remove volatile content from CLAUDE.md",
+    action: "Move dates, TODOs, and 'updated' notes into a separate scratch file. A stable CLAUDE.md keeps the cache warm across sessions instead of resetting it."
+  },
+  cmd_scope: {
+    title: "Keep CLAUDE.md to stable facts",
+    action: "Limit CLAUDE.md to durable conventions and project facts. Changing notes belong elsewhere so the cached prefix stays constant."
+  },
+  clear_between: {
+    title: "Clear or compact between unrelated tasks",
+    action: "Run /clear or compact when you switch to an unrelated task so stale context stops riding along and inflating every turn."
+  },
+  plan_first: {
+    title: "Plan before acting on multi-step work",
+    action: "Use plan mode or write a short spec for multi-step tasks. Planning first cuts the reactive tool loops that burn tokens."
+  },
+  success_criteria: {
+    title: "Give the agent success criteria",
+    action: "State the done condition or point at a test so the agent can verify its own work instead of guessing and retrying."
+  },
+  session_scope: {
+    title: "Scope sessions to one task",
+    action: "Start a fresh session per task and reset between them. Long marathon sessions carry a growing, expensive context."
+  },
+  mcp_scoped: {
+    title: "Trim unused MCP servers and tools",
+    action: "Disable MCP servers and tools you do not use. Every loaded tool definition is context you pay for on every turn."
+  },
+  permission_allowlist: {
+    title: "Set a permission allowlist",
+    action: "Add a settings allowlist for safe, frequent commands to cut approval prompts and the round trips they cost."
+  },
+  bash_reliance: {
+    title: "Use dedicated tools over Bash",
+    action: "Replace shelling out for search and file reads with Grep, Glob, and Read. They are cheaper, cleaner, and easier to permission."
+  },
+  cost_monitor: {
+    title: "Track your spend",
+    action: "Watch token spend or set a budget so a runaway session is caught early rather than at the monthly bill."
+  },
+  model_choice: {
+    title: "Match the model to the task",
+    action: "Use a cheaper model for routine edits and reserve the top model for the hard reasoning. Same work, lower bill."
+  }
+};
+function severityRank(s) {
+  return s === "critical" ? 3 : s === "warn" ? 2 : 1;
+}
+function sizeFix(cmd) {
+  if (cmd.chars > 6e3) {
+    return {
+      title: "Trim your CLAUDE.md",
+      action: "Your CLAUDE.md is large and rides on every turn. Cut it to the durable conventions the agent actually needs and move the rest into docs it can open on demand."
+    };
+  }
+  return {
+    title: "Flesh out your CLAUDE.md",
+    action: "Your CLAUDE.md is thin. Add the conventions, commands, and constraints the agent keeps getting wrong so it stops re-deriving them every session."
+  };
+}
+function synthesize(report, pillars, cmd) {
+  const headlineWasteUsd = cacheMissExposureUsd(report);
+  const headlineWasteLabel = "Recoverable spend (cache-miss exposure)";
+  const spend = report.summary.cost_usd;
+  const exposure = headlineWasteUsd;
+  const fixes = [];
+  const covered = /* @__PURE__ */ new Set();
+  const round22 = (n) => Math.round(n * 100) / 100;
+  const usd2 = (n) => `$${round22(n).toFixed(2)}`;
+  const sevForUsd = (n) => n >= 50 ? "critical" : n >= 10 ? "warn" : "info";
+  const exposureMaterial = exposure >= 1 && (spend === 0 || exposure / spend >= 0.05);
+  if (exposureMaterial) {
+    const ranked = report.projects.map((p) => {
+      const rate = priceFor(p.modelPrimary);
+      const contrib = (p.totals.input_tokens + p.totals.cache_creation_tokens) * (rate.input - rate.cache_read) / 1e6;
+      return { slug: p.slug, contrib };
+    }).filter((r) => r.contrib > 0).sort((a, b) => b.contrib - a.contrib);
+    const worst = ranked.slice(0, 3).map((r) => r.slug);
+    fixes.push({
+      id: "cache_recovery",
+      title: "Recover spend lost to cache misses",
+      pillar: "context_hygiene",
+      pillarName: PILLARS.context_hygiene.name,
+      severity: sevForUsd(exposure),
+      wasteUsd: round22(exposure),
+      problem: sanitizeText(
+        `Up to ${usd2(exposure)} of input spend was paid at full price instead of the cache-read rate. Biggest contributors: ${worst.length ? worst.join(", ") : "your largest projects"}.`
+      ),
+      action: sanitizeText(
+        "Keep the start of each session stable (a steady CLAUDE.md and consistent first reads) so the prompt cache is reused across turns and sessions."
+      ),
+      basis: sanitizeText("Cache-miss exposure summed across projects at the published input minus cache-read delta. Upper bound on recoverable spend.")
+    });
+    covered.add("cache_hit");
+    covered.add("cache_churn");
+    covered.add("recoverable_exposure");
+  }
+  const heavyByTool = /* @__PURE__ */ new Map();
+  let shortCount = 0;
+  for (const f of report.findings) {
+    if (f.ruleId === "HEAVY_TOOL_LOOPS" && f.evidence) {
+      const tool = String(f.evidence["tool"] ?? "a tool");
+      const entry = heavyByTool.get(tool) ?? { sessions: /* @__PURE__ */ new Set(), maxFires: 0 };
+      const sid = f.evidence["sessionUuid"];
+      if (typeof sid === "string") entry.sessions.add(sid);
+      entry.maxFires = Math.max(entry.maxFires, Number(f.evidence["fires"]) || 0);
+      heavyByTool.set(tool, entry);
+      covered.add("tool_thrash");
+    } else if (f.ruleId === "SHORT_SESSION_BLOAT") {
+      shortCount += 1;
+      covered.add("short_session_bloat");
+    }
+  }
+  for (const [tool, e] of heavyByTool) {
+    const n = Math.max(e.sessions.size, 1);
+    fixes.push({
+      id: `heavy_tool_${tool}`,
+      title: `Heavy ${tool} usage in ${n} session(s)`,
+      pillar: "prompting",
+      pillarName: PILLARS.prompting.name,
+      severity: "warn",
+      wasteUsd: 0,
+      problem: sanitizeText(`${tool} fired ${e.maxFires}+ times in a single session across ${n} session(s), a sign of stuck loops or unscoped work.`),
+      action: sanitizeText(`Add a guard or narrow tasks so ${tool} is not called in a tight loop.`),
+      basis: sanitizeText("Aggregated from per-session tool-use counts over the heavy-loop threshold.")
+    });
+  }
+  if (shortCount > 0) {
+    fixes.push({
+      id: "short_sessions",
+      title: `${shortCount} short session(s) cost more than expected`,
+      pillar: "session_mgmt",
+      pillarName: PILLARS.session_mgmt.name,
+      severity: "warn",
+      wasteUsd: 0,
+      problem: sanitizeText(`${shortCount} short session(s) carried a large context for a small task.`),
+      action: sanitizeText("Start a fresh, tightly scoped session for short tasks instead of carrying a big context."),
+      basis: sanitizeText("Sessions under the short-duration threshold with above-floor cost.")
+    });
+  }
+  for (const p of pillars) {
+    for (const c of p.checks) {
+      if (!c.gap || covered.has(c.id)) continue;
+      const tmpl = c.id === "cmd_size" ? sizeFix(cmd) : CHECK_FIX[c.id];
+      if (!tmpl) continue;
+      const severity = (c.score ?? 100) < 40 ? "warn" : "info";
+      fixes.push({
+        id: `check_${c.id}`,
+        title: tmpl.title,
+        pillar: p.id,
+        pillarName: p.name,
+        severity,
+        wasteUsd: 0,
+        problem: c.basis,
+        action: tmpl.action,
+        basis: `${p.name} gap (${c.label}).`
+      });
+    }
+  }
+  fixes.sort((a, b) => {
+    if (b.wasteUsd !== a.wasteUsd) return b.wasteUsd - a.wasteUsd;
+    if (severityRank(b.severity) !== severityRank(a.severity)) return severityRank(b.severity) - severityRank(a.severity);
+    return PILLARS[b.pillar].weight - PILLARS[a.pillar].weight;
+  });
+  return {
+    headlineWasteUsd,
+    headlineWasteLabel,
+    fixes
+  };
+}
+
+// ../../packages/engine/src/audit.ts
+import { randomUUID } from "crypto";
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+function round4(n) {
+  return Math.round(n * 1e4) / 1e4;
+}
+function toUsageMetrics(report) {
+  const s = report.summary;
+  const topProjects = report.projects.slice().sort((a, b) => b.cost_usd - a.cost_usd).slice(0, 8).map((p) => ({
+    slug: p.slug,
+    costUsd: round2(p.cost_usd),
+    sessionsCount: p.sessionsCount,
+    cacheHitRate: round4(p.cacheHitRate),
+    modelPrimary: p.modelPrimary
+  }));
+  const topSessions = report.projects.flatMap((p) => p.sessions.map((sess) => ({ projectSlug: p.slug, sess }))).sort((a, b) => b.sess.cost_usd - a.sess.cost_usd).slice(0, 8).map(({ projectSlug, sess }) => ({
+    projectSlug,
+    sessionUuid: sess.sessionUuid,
+    costUsd: round2(sess.cost_usd),
+    durationMinutes: sess.durationMinutes == null ? null : round2(sess.durationMinutes),
+    modelPrimary: sess.modelPrimary,
+    cacheHitRate: round4(cacheHitRate(sess.totals))
+  }));
+  const modelBreakdown = {};
+  for (const [model, usd2] of Object.entries(s.modelBreakdown)) modelBreakdown[model] = round2(usd2);
+  return {
+    spendUsd: round2(s.cost_usd),
+    cacheSavingsUsd: round2(s.cache_savings_usd),
+    cacheHitRate: round4(s.cacheHitRate),
+    totalTokens: { ...s.totals },
+    sessionsCount: s.sessionsCount,
+    projectsCount: s.projectsCount,
+    durationHours: round2(s.durationHours),
+    modelBreakdown,
+    topProjects,
+    topSessions,
+    pricingSnapshotDate: PRICING_SNAPSHOT_DATE
+  };
+}
+function cleanFix(f) {
+  return {
+    ...f,
+    title: sanitizeText(f.title),
+    problem: sanitizeText(f.problem),
+    action: sanitizeText(f.action),
+    basis: sanitizeText(f.basis),
+    wasteUsd: round2(f.wasteUsd)
+  };
+}
+function cleanCheck(c) {
+  return { ...c, basis: sanitizeText(c.basis) };
+}
+function cleanPillar(p) {
+  return { ...p, checks: p.checks.map(cleanCheck) };
+}
+function buildAudit(input, opts = {}) {
+  const report = analyzeUploads(input.logs);
+  const cmd = analyzeClaudeMd(input.claudeMd);
+  const { pillars, overall, band } = scorePillars(report, cmd, input.questionnaire);
+  const { headlineWasteUsd, headlineWasteLabel, fixes } = synthesize(report, pillars, cmd);
+  const answered = Object.values(input.questionnaire).filter((v) => typeof v === "string" && v.length > 0).length;
+  return {
+    id: randomUUID(),
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    contactEmail: input.contactEmail?.trim() || null,
+    inputsSummary: {
+      logFiles: input.logs.length,
+      hasClaudeMd: cmd.present,
+      claudeMdChars: cmd.chars,
+      questionnaireAnswered: answered
+    },
+    usageMetrics: toUsageMetrics(report),
+    pillarScores: pillars.map(cleanPillar),
+    overallScore: overall,
+    band: { ...band, description: sanitizeText(band.description) },
+    headlineWasteUsd: round2(headlineWasteUsd),
+    headlineWasteLabel: sanitizeText(headlineWasteLabel),
+    fixes: fixes.map(cleanFix),
+    writer: opts.writer ?? "template",
+    paid: false
+  };
+}
+
+// ../../packages/engine/src/validate.ts
+var MAX_FILE_BYTES = 25 * 1024 * 1024;
+var MAX_TOTAL_BYTES = 60 * 1024 * 1024;
+var MAX_CLAUDEMD_BYTES = 1 * 1024 * 1024;
+
+// src/read-sessions.ts
+import { readdir, readFile } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+function defaultProjectsPath() {
+  return process.env.CLAUDE_PROJECTS_PATH || join(homedir(), ".claude", "projects");
+}
+async function readSessions(rootPath) {
+  const logs = [];
+  const skipped = [];
+  let projectDirs;
+  try {
+    projectDirs = await readdir(rootPath, { withFileTypes: true });
+  } catch {
+    return { logs, skipped };
+  }
+  for (const dir of projectDirs) {
+    if (!dir.isDirectory()) continue;
+    const projPath = join(rootPath, dir.name);
+    let files;
+    try {
+      files = await readdir(projPath, { withFileTypes: true });
+    } catch {
+      skipped.push(dir.name);
+      continue;
+    }
+    for (const f of files) {
+      if (!f.isFile() || !f.name.endsWith(".jsonl")) continue;
+      const rel = `${dir.name}/${f.name}`;
+      try {
+        const text = await readFile(join(projPath, f.name), "utf8");
+        logs.push({ name: rel, text });
+      } catch {
+        skipped.push(rel);
+      }
+    }
+  }
+  return { logs, skipped };
+}
+
+// src/format.ts
+function usd(n) {
+  return `$${(Math.round(n * 100) / 100).toFixed(2)}`;
+}
+function bar(score, width = 20) {
+  if (score === null) return "n/a";
+  const filled = Math.round(score / 100 * width);
+  return `[${"#".repeat(filled)}${".".repeat(width - filled)}] ${score}`;
+}
+function formatAudit(record, meta) {
+  const m = record.usageMetrics;
+  const lines = [];
+  lines.push("CostClaw audit");
+  lines.push(`Source: ${meta.root} (${meta.sessionCount} sessions across ${m.projectsCount} projects)`);
+  lines.push("");
+  lines.push(`${record.headlineWasteLabel}: ${usd(record.headlineWasteUsd)}`);
+  lines.push("");
+  lines.push(`Spend analyzed: ${usd(m.spendUsd)}    Cache hit: ${(m.cacheHitRate * 100).toFixed(1)}%    Active hours: ${m.durationHours.toFixed(1)}`);
+  lines.push(`Pricing snapshot: ${m.pricingSnapshotDate}`);
+  lines.push("");
+  lines.push(`Overall setup score: ${record.overallScore} / 100  (${record.band.label})`);
+  for (const p of record.pillarScores) {
+    lines.push(`  ${p.name.padEnd(22)} ${bar(p.score)}`);
+  }
+  lines.push("");
+  const dollarFixes = record.fixes.filter((f) => f.wasteUsd > 0);
+  const otherIssues = record.fixes.filter((f) => f.wasteUsd === 0);
+  lines.push("Top fixes by recoverable spend:");
+  if (dollarFixes.length === 0) {
+    lines.push("  No directly recoverable dollars found. See issues below.");
+  } else {
+    for (const f of dollarFixes.slice(0, 6)) {
+      lines.push(`  - [${usd(f.wasteUsd)}] ${f.title}`);
+      lines.push(`      ${f.action}`);
+    }
+  }
+  if (otherIssues.length > 0) {
+    lines.push("");
+    lines.push("Other issues to tighten:");
+    for (const f of otherIssues.slice(0, 6)) {
+      lines.push(`  - ${f.title}`);
+    }
+    if (otherIssues.length > 6) {
+      lines.push(`  ... and ${otherIssues.length - 6} more`);
+    }
+  }
+  if (meta.skipped.length > 0) {
+    lines.push("");
+    lines.push(`Note: ${meta.skipped.length} file(s) could not be read and were skipped.`);
+  }
+  lines.push("");
+  lines.push("Tip: answer the hygiene questionnaire on the web for a fuller score. Nothing left your machine.");
+  return lines.join("\n");
+}
+
+// src/audit-command.ts
+async function runAudit(opts) {
+  const root = opts.path || defaultProjectsPath();
+  const { logs, skipped } = await readSessions(root);
+  if (logs.length === 0) {
+    throw new Error(`No .jsonl sessions found under ${root}. Set CLAUDE_PROJECTS_PATH or pass --path <dir>.`);
+  }
+  let claudeMd;
+  if (opts.claudeMdPath) {
+    claudeMd = await readFile2(opts.claudeMdPath, "utf8");
+  }
+  const record = buildAudit({ logs, claudeMd, questionnaire: {} });
+  const output = opts.json ? JSON.stringify(record, null, 2) : formatAudit(record, { root, sessionCount: logs.length, skipped });
+  return { output, record };
+}
+
+// src/index.ts
+process.on("unhandledRejection", (reason) => {
+  console.error("Unhandled rejection:", reason);
+  process.exit(1);
+});
+function getFlag(args, name) {
+  const i = args.indexOf(name);
+  return i >= 0 && i + 1 < args.length ? args[i + 1] : void 0;
+}
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  if (command === "audit") {
+    const { output } = await runAudit({
+      path: getFlag(args, "--path"),
+      claudeMdPath: getFlag(args, "--claude-md"),
+      json: args.includes("--json")
+    });
+    process.stdout.write(output + "\n");
+    return;
+  }
+  process.stderr.write(
+    [
+      "CostClaw - privacy-first Claude Code cost and setup audit",
+      "",
+      "Usage:",
+      "  costclaw audit [--path <dir>] [--claude-md <file>] [--json]",
+      "",
+      "Reads your Claude Code logs from ~/.claude/projects (or --path) on this machine,",
+      "and prints a cost report plus a six-pillar setup score. Nothing is uploaded.",
+      ""
+    ].join("\n") + "\n"
+  );
+  process.exit(command ? 1 : 0);
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "costclaw",
+  "version": "0.1.0",
+  "description": "Local cost and setup audit for Claude Code. Finds recoverable token spend and scores your setup across six pillars, with your prompts never leaving your machine.",
+  "type": "module",
+  "bin": { "costclaw": "dist/index.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=20" },
+  "license": "UNLICENSED",
+  "homepage": "https://costclaw.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ucsandman/costclaw.git",
+    "directory": "apps/cli"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "anthropic",
+    "cost",
+    "finops",
+    "audit",
+    "tokens",
+    "cli"
+  ],
+  "scripts": {
+    "audit": "tsx src/index.ts audit",
+    "dev": "tsx src/index.ts",
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@costclaw/engine": "*",
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.8"
+  }
+}