clawculator 2.2.0 → 2.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawculator",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "AI cost forensics for OpenClaw and multi-model setups. Your friendly penny pincher. 100% offline. Zero AI. Pure deterministic logic.",
   "main": "src/analyzer.js",
   "bin": {

package/skills/clawculator/analyzer.js

@@ -347,8 +347,8 @@ function analyzeConfig(configPath) {
   const hooks = config.hooks?.internal?.entries || config.hooks || {};
   const hookNames = Object.keys(hooks).filter(k => k !== 'enabled' && k !== 'token' && k !== 'path');
   let hookIssues = 0;
-
   let haikuHooks = 0;
+
   for (const name of hookNames) {
     const hook = typeof hooks[name] === 'object' ? hooks[name] : {};
     if (hook.enabled === false) continue;
@@ -500,14 +500,120 @@ function analyzeConfig(configPath) {
 }
 
 // ── Session analysis ──────────────────────────────────────────────
+
+/**
+ * Parse a .jsonl session transcript file and sum up real usage/cost data.
+ * Returns { input, output, cacheRead, cacheWrite, totalTokens, totalCost, messageCount, model, firstTs, lastTs }
+ */
+function parseTranscript(jsonlPath) {
+  try {
+    const content = fs.readFileSync(jsonlPath, 'utf8').trim();
+    if (!content) return null;
+
+    let input = 0, output = 0, cacheRead = 0, cacheWrite = 0, totalTokens = 0, totalCost = 0;
+    let messageCount = 0, model = null, firstTs = null, lastTs = null;
+
+    for (const line of content.split('\n')) {
+      if (!line.trim()) continue;
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+
+      // Track timestamps from all message types
+      const ts = entry.timestamp || entry.message?.timestamp;
+      if (ts) {
+        const t = typeof ts === 'number' ? ts : new Date(ts).getTime();
+        if (!firstTs || t < firstTs) firstTs = t;
+        if (!lastTs  || t > lastTs)  lastTs = t;
+      }
+
+      // Only assistant messages with usage blocks have cost data
+      if (entry.type !== 'message') continue;
+
+      // Usage can be at entry.usage (some formats) or entry.message.usage (standard format)
+      const u = entry.usage || entry.message?.usage;
+      if (!u) continue;
+
+      messageCount++;
+
+      // Model can be at entry.model or entry.message.model
+      const entryModel = entry.model || entry.message?.model;
+      if (entryModel && !model) model = entryModel;
+
+      input       += u.input       || 0;
+      output      += u.output      || 0;
+      cacheRead   += u.cacheRead   || 0;
+      cacheWrite  += u.cacheWrite  || 0;
+      totalTokens += u.totalTokens || 0;
+
+      // Prefer API-reported cost (already accounts for cache pricing)
+      if (u.cost) {
+        if (typeof u.cost === 'object' && u.cost.total != null) {
+          totalCost += u.cost.total;
+        } else if (typeof u.cost === 'number') {
+          totalCost += u.cost;
+        }
+      }
+    }
+
+    if (messageCount === 0) return null;
+
+    return { input, output, cacheRead, cacheWrite, totalTokens, totalCost, messageCount, model, firstTs, lastTs };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Discover all agent session directories (not just main).
+ */
+function discoverAgentDirs() {
+  const openclawHome = process.env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw');
+  const agentsDir = path.join(openclawHome, 'agents');
+  const dirs = [];
+  try {
+    for (const agent of fs.readdirSync(agentsDir)) {
+      const sessionsDir = path.join(agentsDir, agent, 'sessions');
+      if (fs.existsSync(sessionsDir) && fs.statSync(sessionsDir).isDirectory()) {
+        dirs.push({ agent, sessionsDir });
+      }
+    }
+  } catch { /* agents dir doesn't exist */ }
+  return dirs;
+}
+
+/**
+ * Discover web-chat session transcripts.
+ */
+function discoverWebChatSessions() {
+  const openclawHome = process.env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw');
+  const webChatDir = path.join(openclawHome, 'web-chat');
+  const sessions = [];
+  try {
+    for (const file of fs.readdirSync(webChatDir)) {
+      if (file.endsWith('.jsonl')) {
+        sessions.push(path.join(webChatDir, file));
+      }
+    }
+  } catch { /* web-chat dir doesn't exist */ }
+  return sessions;
+}
+
 function analyzeSessions(sessionsPath) {
   const findings = [];
   const sessions = readJSON(sessionsPath);
+  const sessionsDir = sessionsPath ? path.dirname(sessionsPath) : null;
 
-  if (!sessions) return { exists: false, findings: [], sessions: [], totalInputTokens: 0, totalOutputTokens: 0, totalCost: 0, sessionCount: 0 };
+  if (!sessions) return { exists: false, findings: [], sessions: [], totalInputTokens: 0, totalOutputTokens: 0, totalCost: 0, totalCacheRead: 0, totalCacheWrite: 0, totalRealCost: 0, sessionCount: 0 };
 
   let totalIn = 0, totalOut = 0, totalCost = 0;
+  let totalCacheRead = 0, totalCacheWrite = 0, totalRealCost = 0;
   const breakdown = [], orphaned = [], large = [];
+  let transcriptHits = 0, transcriptMisses = 0;
+
+  // Track which sessionIds we've already parsed to avoid double-counting
+  // (multiple session keys can share the same sessionId / .jsonl file)
+  const parsedTranscripts = new Map(); // sessionId -> transcript result
+  const countedSessionIds = new Set();
 
   for (const key of Object.keys(sessions)) {
     const s        = sessions[key];
@@ -515,31 +621,185 @@ function analyzeSessions(sessionsPath) {
     const modelKey = resolveModel(model);
     const inTok    = s.inputTokens  || s.tokensIn  || s.tokens?.input  || 0;
     const outTok   = s.outputTokens || s.tokensOut || s.tokens?.output || 0;
-    const cost     = costPerCall(modelKey, inTok, outTok);
+    const estimatedCost = costPerCall(modelKey, inTok, outTok);
     const updatedAt = s.updatedAt || s.lastActive || null;
 
-    totalIn   += inTok;
-    totalOut  += outTok;
-    totalCost += cost;
+    // Look up transcript by sessionId (not by key name)
+    let transcript = null;
+    const sessionId = s.sessionId;
+    if (sessionsDir && sessionId) {
+      if (parsedTranscripts.has(sessionId)) {
+        transcript = parsedTranscripts.get(sessionId);
+      } else {
+        const jsonlPath = path.join(sessionsDir, `${sessionId}.jsonl`);
+        transcript = parseTranscript(jsonlPath);
+        parsedTranscripts.set(sessionId, transcript);
+      }
+    }
+
+    // Deduplicate: if multiple keys share a sessionId, only count transcript cost once
+    const isSharedSession = sessionId && countedSessionIds.has(sessionId);
+    if (sessionId) countedSessionIds.add(sessionId);
+
+    // Use transcript data when available, fall back to sessions.json estimates
+    let realIn, realOut, realCacheRead, realCacheWrite, realCost, realModel, realTotalTokens;
+    if (transcript && !isSharedSession) {
+      transcriptHits++;
+      realIn         = transcript.input;
+      realOut        = transcript.output;
+      realCacheRead  = transcript.cacheRead;
+      realCacheWrite = transcript.cacheWrite;
+      realCost       = transcript.totalCost;
+      realModel      = transcript.model || model;
+      realTotalTokens = transcript.totalTokens;
+    } else if (transcript && isSharedSession) {
+      // Shared sessionId — transcript already counted, show it but zero out cost
+      transcriptHits++;
+      realIn         = 0;
+      realOut        = 0;
+      realCacheRead  = 0;
+      realCacheWrite = 0;
+      realCost       = 0;
+      realModel      = transcript.model || model;
+      realTotalTokens = 0;
+    } else {
+      transcriptMisses++;
+      realIn         = inTok;
+      realOut        = outTok;
+      realCacheRead  = 0;
+      realCacheWrite = 0;
+      realCost       = estimatedCost;
+      realModel      = model;
+      realTotalTokens = inTok + outTok;
+    }
+
+    totalIn         += realIn;
+    totalOut        += realOut;
+    totalCacheRead  += realCacheRead;
+    totalCacheWrite += realCacheWrite;
+    totalCost       += estimatedCost;
+    totalRealCost   += realCost;
+
+    const allTokens = realTotalTokens || (realIn + realOut + realCacheRead + realCacheWrite);
 
     const isOrphaned = key.includes('cron') || key.includes('deleted') ||
       (updatedAt && Date.now() - new Date(updatedAt).getTime() > 48 * 3600 * 1000 && !key.includes('main'));
 
-    if (isOrphaned) orphaned.push({ key, model, tokens: inTok + outTok, cost });
-    if (inTok + outTok > 50000) large.push({ key, model, tokens: inTok + outTok });
+    if (isOrphaned) orphaned.push({ key, model: realModel, tokens: allTokens, cost: realCost });
+    if (allTokens > 50000) large.push({ key, model: realModel, tokens: allTokens });
 
     const ageMs    = updatedAt ? Date.now() - new Date(updatedAt).getTime() : null;
     const ageDays  = ageMs ? ageMs / (1000 * 3600 * 24) : null;
-    const dailyCost = (ageDays && ageDays > 0.01 && cost > 0) ? cost / ageDays : null;
+    const dailyCost = (ageDays && ageDays > 0.01 && realCost > 0) ? realCost / ageDays : null;
+
+    const realModelKey = resolveModel(realModel);
+    breakdown.push({
+      key, sessionId: sessionId || null, model: realModel,
+      modelLabel: realModelKey ? (MODEL_PRICING[realModelKey]?.label || realModelKey) : (modelKey ? (MODEL_PRICING[modelKey]?.label || modelKey) : 'unknown'),
+      inputTokens: realIn, outputTokens: realOut,
+      cacheRead: realCacheRead, cacheWrite: realCacheWrite,
+      cost: realCost, estimatedCost,
+      hasTranscript: !!transcript,
+      isSharedSession,
+      messageCount: transcript?.messageCount || 0,
+      updatedAt, ageMs, dailyCost, isOrphaned,
+    });
+  }
 
-    breakdown.push({ key, model, modelLabel: modelKey ? (MODEL_PRICING[modelKey]?.label || modelKey) : 'unknown', inputTokens: inTok, outputTokens: outTok, cost, updatedAt, ageMs, dailyCost, isOrphaned });
+  // Scan for untracked .jsonl files (sessions not in sessions.json)
+  const trackedIds = new Set(Object.values(sessions).map(s => s.sessionId).filter(Boolean));
+  let untrackedCount = 0, untrackedCost = 0, untrackedTokens = 0;
+  if (sessionsDir) {
+    try {
+      for (const file of fs.readdirSync(sessionsDir)) {
+        if (!file.endsWith('.jsonl')) continue;
+        const fileId = file.replace('.jsonl', '');
+        if (trackedIds.has(fileId)) continue; // already counted
+        const transcript = parseTranscript(path.join(sessionsDir, file));
+        if (transcript && transcript.messageCount > 0) {
+          untrackedCount++;
+          untrackedCost += transcript.totalCost;
+          untrackedTokens += transcript.totalTokens;
+          totalRealCost += transcript.totalCost;
+          totalCacheRead += transcript.cacheRead;
+          totalCacheWrite += transcript.cacheWrite;
+          breakdown.push({
+            key: `untracked:${fileId.slice(0, 8)}`, sessionId: fileId, model: transcript.model,
+            modelLabel: transcript.model ? (MODEL_PRICING[resolveModel(transcript.model)]?.label || transcript.model) : 'unknown',
+            inputTokens: transcript.input, outputTokens: transcript.output,
+            cacheRead: transcript.cacheRead, cacheWrite: transcript.cacheWrite,
+            cost: transcript.totalCost, estimatedCost: 0,
+            hasTranscript: true, isSharedSession: false,
+            messageCount: transcript.messageCount,
+            updatedAt: transcript.lastTs ? new Date(transcript.lastTs).toISOString() : null,
+            ageMs: transcript.lastTs ? Date.now() - transcript.lastTs : null,
+            dailyCost: null, isOrphaned: false, isUntracked: true,
+          });
+        }
+      }
+    } catch { /* can't read dir */ }
   }
 
+  if (untrackedCount > 0) {
+    findings.push({
+      severity: untrackedCost > 1 ? 'high' : 'medium',
+      source: 'sessions',
+      message: `${untrackedCount} untracked session(s) found — .jsonl files not in sessions.json`,
+      detail: `${untrackedTokens.toLocaleString()} tokens · $${untrackedCost.toFixed(4)} in API costs\nThese are old/deleted sessions still on disk with real spend data`,
+    });
+  }
+
+  // Findings
   if (orphaned.length > 0) findings.push({ severity: 'high', source: 'sessions', message: `${orphaned.length} orphaned session(s) — still holding tokens on paid models`, detail: orphaned.map(s => `${s.key}: ${s.tokens.toLocaleString()} tokens ($${s.cost.toFixed(4)})`).join('\n  '), ...FIXES.ORPHANED_SESSIONS });
   if (large.length > 0) findings.push({ severity: 'medium', source: 'sessions', message: `${large.length} session(s) with >50k tokens per conversation`, detail: large.map(s => `${s.key}: ${s.tokens.toLocaleString()} tokens`).join('\n  '), ...FIXES.LARGE_SESSIONS });
   if (Object.keys(sessions).length > 0 && !orphaned.length && !large.length) findings.push({ severity: 'info', source: 'sessions', message: `${Object.keys(sessions).length} session(s) healthy ✓`, detail: `Total tokens: ${(totalIn + totalOut).toLocaleString()}` });
 
-  return { exists: true, findings, sessions: breakdown, totalInputTokens: totalIn, totalOutputTokens: totalOut, totalCost, sessionCount: Object.keys(sessions).length };
+  // Cache cost finding
+  if (totalCacheWrite > 0 || totalCacheRead > 0) {
+    const cacheDetail = [];
+    if (totalCacheRead > 0)  cacheDetail.push(`Cache reads: ${totalCacheRead.toLocaleString()} tokens`);
+    if (totalCacheWrite > 0) cacheDetail.push(`Cache writes: ${totalCacheWrite.toLocaleString()} tokens`);
+    const cacheCostPortion = totalRealCost - totalCost;
+    if (cacheCostPortion > 0.01) {
+      findings.push({
+        severity: cacheCostPortion > 1 ? 'high' : 'medium',
+        source: 'sessions',
+        message: `Prompt caching added $${cacheCostPortion.toFixed(4)} beyond base token costs`,
+        detail: cacheDetail.join('\n  ') + `\n  Cache writes are 3.75x input cost · Cache reads are 0.1x input cost`,
+        monthlyCost: 0, // already counted in session costs, not a recurring config bleed
+      });
+    } else {
+      findings.push({ severity: 'info', source: 'sessions', message: `Prompt caching active — ${(totalCacheRead + totalCacheWrite).toLocaleString()} cache tokens tracked`, detail: cacheDetail.join(' · ') });
+    }
+  }
+
+  // Transcript coverage finding
+  if (transcriptHits > 0 || transcriptMisses > 0) {
+    const total = transcriptHits + transcriptMisses;
+    if (transcriptMisses > 0 && transcriptHits > 0) {
+      findings.push({ severity: 'info', source: 'sessions', message: `Transcript data: ${transcriptHits}/${total} sessions have .jsonl transcripts (${transcriptMisses} estimated)`, detail: `Sessions with transcripts show real API-reported costs including cache tokens` });
+    }
+  }
+
+  // Cost discrepancy finding
+  if (totalRealCost > 0 && totalCost > 0) {
+    const ratio = totalRealCost / totalCost;
+    if (ratio > 2) {
+      findings.push({
+        severity: 'high',
+        source: 'sessions',
+        message: `Real cost $${totalRealCost.toFixed(4)} is ${ratio.toFixed(1)}x higher than sessions.json estimate ($${totalCost.toFixed(4)})`,
+        detail: `sessions.json only tracks input/output tokens — cache tokens, which are the bulk of real spending, are only in .jsonl transcripts`,
+      });
+    }
+  }
+
+  return {
+    exists: true, findings, sessions: breakdown,
+    totalInputTokens: totalIn, totalOutputTokens: totalOut,
+    totalCost, totalCacheRead, totalCacheWrite, totalRealCost,
+    sessionCount: Object.keys(sessions).length,
+  };
 }
 
 // ── Workspace analysis ────────────────────────────────────────────
@@ -568,12 +828,64 @@ async function runAnalysis({ configPath, sessionsPath, logsDir }) {
   const sessionResult   = analyzeSessions(sessionsPath);
   const workspaceResult = analyzeWorkspace();
 
-  const allFindings = [...configResult.findings, ...sessionResult.findings, ...workspaceResult.findings];
+  // Scan additional agent folders beyond main
+  const agentDirs = discoverAgentDirs();
+  const additionalAgentSessions = [];
+  for (const { agent, sessionsDir } of agentDirs) {
+    const sjPath = path.join(sessionsDir, 'sessions.json');
+    // Skip the primary sessions path (already analyzed above)
+    if (sjPath === sessionsPath) continue;
+    if (fs.existsSync(sjPath)) {
+      const extra = analyzeSessions(sjPath);
+      if (extra.exists) {
+        additionalAgentSessions.push({ agent, ...extra });
+      }
+    }
+  }
+
+  // Scan web-chat sessions
+  const webChatPaths = discoverWebChatSessions();
+  const webChatSessions = [];
+  for (const wcp of webChatPaths) {
+    const transcript = parseTranscript(wcp);
+    if (transcript) {
+      const sessionId = path.basename(wcp, '.jsonl');
+      webChatSessions.push({ key: `web-chat/${sessionId}`, ...transcript });
+    }
+  }
+
+  // Merge all findings
+  const allFindings = [
+    ...configResult.findings,
+    ...sessionResult.findings,
+    ...workspaceResult.findings,
+  ];
+
+  // Add additional agent findings
+  for (const extra of additionalAgentSessions) {
+    if (extra.findings.length > 0) {
+      allFindings.push({ severity: 'info', source: 'sessions', message: `Agent "${extra.agent}": ${extra.sessionCount} session(s) found`, detail: `Tokens: ${(extra.totalInputTokens + extra.totalOutputTokens).toLocaleString()} · Cost: $${extra.totalRealCost.toFixed(4)}` });
+    }
+    // Merge their sessions into the main breakdown
+    sessionResult.sessions.push(...(extra.sessions || []));
+    sessionResult.totalRealCost += extra.totalRealCost || 0;
+    sessionResult.totalCacheRead += extra.totalCacheRead || 0;
+    sessionResult.totalCacheWrite += extra.totalCacheWrite || 0;
+  }
+
+  // Add web-chat finding if any
+  if (webChatSessions.length > 0) {
+    const wcTotal = webChatSessions.reduce((sum, s) => sum + s.totalCost, 0);
+    const wcTokens = webChatSessions.reduce((sum, s) => sum + s.totalTokens, 0);
+    allFindings.push({ severity: 'info', source: 'sessions', message: `${webChatSessions.length} web-chat session(s) found`, detail: `Tokens: ${wcTokens.toLocaleString()} · Cost: $${wcTotal.toFixed(4)}` });
+  }
 
   const estimatedMonthlyBleed = allFindings
     .filter(f => f.monthlyCost && f.severity !== 'info')
     .reduce((sum, f) => sum + f.monthlyCost, 0);
 
+  const realCost = sessionResult.totalRealCost || 0;
+
   return {
     scannedAt:    new Date().toISOString(),
     configPath,
@@ -589,10 +901,15 @@ async function runAnalysis({ configPath, sessionsPath, logsDir }) {
       estimatedMonthlyBleed,
       sessionsAnalyzed:      sessionResult.sessionCount,
       totalTokensFound:      (sessionResult.totalInputTokens || 0) + (sessionResult.totalOutputTokens || 0),
+      totalCacheRead:        sessionResult.totalCacheRead || 0,
+      totalCacheWrite:       sessionResult.totalCacheWrite || 0,
+      totalRealCost:         realCost,
+      totalEstimatedCost:    sessionResult.totalCost || 0,
     },
     sessions: sessionResult.sessions || [],
+    webChatSessions,
     config:   configResult.config,
   };
 }
 
-module.exports = { runAnalysis, MODEL_PRICING, resolveModel, costPerCall };
+module.exports = { runAnalysis, MODEL_PRICING, resolveModel, costPerCall, parseTranscript, discoverAgentDirs, discoverWebChatSessions };

package/skills/clawculator/htmlReport.js

@@ -79,14 +79,16 @@ async function generateHTMLReport(analysis, outPath) {
     .map(s => {
       const keyDisplay = s.key.length > 12 ? s.key.slice(0, 8) + '…' : s.key;
       const flag = s.isOrphaned ? ' ⚠️' : '';
+      const txBadge = s.hasTranscript ? '<span style="color:#22c55e; font-size:10px; margin-left:4px" title="Cost from .jsonl transcript (API-reported)">●</span>' : '<span style="color:#6b7280; font-size:10px; margin-left:4px" title="Estimated cost (no transcript found)">○</span>';
       const age = s.ageMs ? relativeAge(s.ageMs) : 'unknown';
       const absDate = s.updatedAt ? new Date(s.updatedAt).toLocaleString() : '';
       const daily = s.dailyCost ? `$${s.dailyCost.toFixed(4)}/day` : '—';
+      const cacheTitle = (s.cacheRead || s.cacheWrite) ? `Cache R: ${(s.cacheRead||0).toLocaleString()} · W: ${(s.cacheWrite||0).toLocaleString()}` : '';
       return `
       <tr style="${s.isOrphaned ? 'background:#fff7ed' : ''}">
-        <td style="padding:8px 12px; font-family:monospace; font-size:13px">${keyDisplay}${flag}</td>
+        <td style="padding:8px 12px; font-family:monospace; font-size:13px">${keyDisplay}${flag}${txBadge}</td>
         <td style="padding:8px 12px">${s.modelLabel || s.model}</td>
-        <td style="padding:8px 12px; text-align:right">${(s.inputTokens + s.outputTokens).toLocaleString()}</td>
+        <td style="padding:8px 12px; text-align:right" title="${cacheTitle}">${(s.inputTokens + s.outputTokens).toLocaleString()}${(s.cacheRead || s.cacheWrite) ? `<span style="color:#6b7280; font-size:11px;"> +${((s.cacheRead||0)+(s.cacheWrite||0)).toLocaleString()} cache</span>` : ''}</td>
         <td style="padding:8px 12px; text-align:right; color:${s.cost > 0.01 ? '#ef4444' : '#22c55e'}">$${s.cost.toFixed(6)}</td>
         <td style="padding:8px 12px; text-align:right; color:#f59e0b">${daily}</td>
         <td style="padding:8px 12px; color:#6b7280; font-size:13px" title="${absDate}">${age}</td>
@@ -138,6 +140,27 @@ async function generateHTMLReport(analysis, outPath) {
       <div style="color:#86efac; font-size:18px; font-weight:700">✅ No significant cost bleed detected</div>
     </div>`}
 
+    ${summary.totalRealCost > 0 ? `
+    <div class="section" style="border:1px solid #f59e0b;">
+      <div class="section-title" style="color:#f59e0b;">💰 Actual API Spend (from transcripts)</div>
+      <div style="display:flex; gap:32px; flex-wrap:wrap; align-items:center;">
+        <div>
+          <div style="font-size:36px; font-weight:900; color:#fbbf24;">$${summary.totalRealCost.toFixed(4)}</div>
+          <div style="font-size:13px; color:#94a3b8; margin-top:4px;">Total real cost (API-reported)</div>
+        </div>
+        ${summary.totalEstimatedCost > 0 && summary.totalRealCost > summary.totalEstimatedCost * 1.1 ? `
+        <div style="background:#451a03; padding:10px 16px; border-radius:8px; border:1px solid #92400e;">
+          <div style="font-size:14px; color:#fbbf24; font-weight:600;">${(summary.totalRealCost / summary.totalEstimatedCost).toFixed(1)}x higher than sessions.json estimate</div>
+          <div style="font-size:12px; color:#d97706; margin-top:2px;">sessions.json: $${summary.totalEstimatedCost.toFixed(4)} — missing cache token costs</div>
+        </div>` : ''}
+      </div>
+      ${summary.totalCacheRead > 0 || summary.totalCacheWrite > 0 ? `
+      <div style="margin-top:16px; display:flex; gap:24px; flex-wrap:wrap;">
+        ${summary.totalCacheWrite > 0 ? `<div style="color:#f97316; font-size:14px;">📝 Cache writes: <strong>${summary.totalCacheWrite.toLocaleString()}</strong> tokens</div>` : ''}
+        ${summary.totalCacheRead > 0 ? `<div style="color:#22c55e; font-size:14px;">📖 Cache reads: <strong>${summary.totalCacheRead.toLocaleString()}</strong> tokens</div>` : ''}
+      </div>` : ''}
+    </div>` : ''}
+
     <div class="cards">
       <div class="card">
         <div class="card-value" style="color:#ef4444">${summary.critical}</div>

package/skills/clawculator/mdReport.js

@@ -69,6 +69,14 @@ function generateMarkdownReport(analysis) {
     if (totalCost > 0)      lines.push(`| Total session cost (lifetime) | $${totalCost.toFixed(4)} |`);
     if (totalDailyRate > 0) lines.push(`| Avg daily burn rate | $${totalDailyRate.toFixed(4)}/day (~$${(totalDailyRate * 30).toFixed(2)}/month) |`);
   }
+  if (summary.totalRealCost > 0) {
+    lines.push(`| 💰 **Actual API spend** | **$${summary.totalRealCost.toFixed(4)}** |`);
+    if (summary.totalEstimatedCost > 0 && summary.totalRealCost > summary.totalEstimatedCost * 1.1) {
+      lines.push(`| sessions.json estimate | $${summary.totalEstimatedCost.toFixed(4)} (${(summary.totalRealCost / summary.totalEstimatedCost).toFixed(1)}x gap) |`);
+    }
+  }
+  if (summary.totalCacheWrite > 0) lines.push(`| Cache writes | ${summary.totalCacheWrite.toLocaleString()} tokens |`);
+  if (summary.totalCacheRead > 0)  lines.push(`| Cache reads | ${summary.totalCacheRead.toLocaleString()} tokens |`);
   lines.push('');
 
   // Findings by severity

package/skills/clawculator/reporter.js

@@ -115,6 +115,15 @@ function generateTerminalReport(analysis) {
   console.log(`${C}━━━ Summary ━━━${R}`);
   console.log(`  🔴 ${RED}${summary.critical}${R} critical  🟠 ${summary.high} high  🟡 ${summary.medium} medium  🔵 ${summary.low||0} low  ✅ ${summary.info} ok`);
   console.log(`  Sessions analyzed: ${summary.sessionsAnalyzed} · Tokens found: ${(summary.totalTokensFound||0).toLocaleString()}`);
+  if (summary.totalCacheRead > 0 || summary.totalCacheWrite > 0) {
+    console.log(`  ${D}Cache tokens: ${(summary.totalCacheRead||0).toLocaleString()} read · ${(summary.totalCacheWrite||0).toLocaleString()} write${R}`);
+  }
+  if (summary.totalRealCost > 0) {
+    console.log(`  ${B}Actual API spend: ${RED}$${summary.totalRealCost.toFixed(4)}${R}${B} (from .jsonl transcripts)${R}`);
+    if (summary.totalEstimatedCost > 0 && summary.totalRealCost > summary.totalEstimatedCost * 1.1) {
+      console.log(`  ${D}sessions.json estimate: $${summary.totalEstimatedCost.toFixed(4)} — ${(summary.totalRealCost / summary.totalEstimatedCost).toFixed(1)}x gap (cache tokens)${R}`);
+    }
+  }
   if (bleed > 0) {
     console.log(`  ${RED}${B}Estimated monthly bleed: $${bleed.toFixed(2)}/month${R}`);
   } else {

package/src/analyzer.js

@@ -500,14 +500,120 @@ function analyzeConfig(configPath) {
 }
 
 // ── Session analysis ──────────────────────────────────────────────
+
+/**
+ * Parse a .jsonl session transcript file and sum up real usage/cost data.
+ * Returns { input, output, cacheRead, cacheWrite, totalTokens, totalCost, messageCount, model, firstTs, lastTs }
+ */
+function parseTranscript(jsonlPath) {
+  try {
+    const content = fs.readFileSync(jsonlPath, 'utf8').trim();
+    if (!content) return null;
+
+    let input = 0, output = 0, cacheRead = 0, cacheWrite = 0, totalTokens = 0, totalCost = 0;
+    let messageCount = 0, model = null, firstTs = null, lastTs = null;
+
+    for (const line of content.split('\n')) {
+      if (!line.trim()) continue;
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+
+      // Track timestamps from all message types
+      const ts = entry.timestamp || entry.message?.timestamp;
+      if (ts) {
+        const t = typeof ts === 'number' ? ts : new Date(ts).getTime();
+        if (!firstTs || t < firstTs) firstTs = t;
+        if (!lastTs  || t > lastTs)  lastTs = t;
+      }
+
+      // Only assistant messages with usage blocks have cost data
+      if (entry.type !== 'message') continue;
+
+      // Usage can be at entry.usage (some formats) or entry.message.usage (standard format)
+      const u = entry.usage || entry.message?.usage;
+      if (!u) continue;
+
+      messageCount++;
+
+      // Model can be at entry.model or entry.message.model
+      const entryModel = entry.model || entry.message?.model;
+      if (entryModel && !model) model = entryModel;
+
+      input       += u.input       || 0;
+      output      += u.output      || 0;
+      cacheRead   += u.cacheRead   || 0;
+      cacheWrite  += u.cacheWrite  || 0;
+      totalTokens += u.totalTokens || 0;
+
+      // Prefer API-reported cost (already accounts for cache pricing)
+      if (u.cost) {
+        if (typeof u.cost === 'object' && u.cost.total != null) {
+          totalCost += u.cost.total;
+        } else if (typeof u.cost === 'number') {
+          totalCost += u.cost;
+        }
+      }
+    }
+
+    if (messageCount === 0) return null;
+
+    return { input, output, cacheRead, cacheWrite, totalTokens, totalCost, messageCount, model, firstTs, lastTs };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Discover all agent session directories (not just main).
+ */
+function discoverAgentDirs() {
+  const openclawHome = process.env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw');
+  const agentsDir = path.join(openclawHome, 'agents');
+  const dirs = [];
+  try {
+    for (const agent of fs.readdirSync(agentsDir)) {
+      const sessionsDir = path.join(agentsDir, agent, 'sessions');
+      if (fs.existsSync(sessionsDir) && fs.statSync(sessionsDir).isDirectory()) {
+        dirs.push({ agent, sessionsDir });
+      }
+    }
+  } catch { /* agents dir doesn't exist */ }
+  return dirs;
+}
+
+/**
+ * Discover web-chat session transcripts.
+ */
+function discoverWebChatSessions() {
+  const openclawHome = process.env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw');
+  const webChatDir = path.join(openclawHome, 'web-chat');
+  const sessions = [];
+  try {
+    for (const file of fs.readdirSync(webChatDir)) {
+      if (file.endsWith('.jsonl')) {
+        sessions.push(path.join(webChatDir, file));
+      }
+    }
+  } catch { /* web-chat dir doesn't exist */ }
+  return sessions;
+}
+
 function analyzeSessions(sessionsPath) {
   const findings = [];
   const sessions = readJSON(sessionsPath);
+  const sessionsDir = sessionsPath ? path.dirname(sessionsPath) : null;
 
-  if (!sessions) return { exists: false, findings: [], sessions: [], totalInputTokens: 0, totalOutputTokens: 0, totalCost: 0, sessionCount: 0 };
+  if (!sessions) return { exists: false, findings: [], sessions: [], totalInputTokens: 0, totalOutputTokens: 0, totalCost: 0, totalCacheRead: 0, totalCacheWrite: 0, totalRealCost: 0, sessionCount: 0 };
 
   let totalIn = 0, totalOut = 0, totalCost = 0;
+  let totalCacheRead = 0, totalCacheWrite = 0, totalRealCost = 0;
   const breakdown = [], orphaned = [], large = [];
+  let transcriptHits = 0, transcriptMisses = 0;
+
+  // Track which sessionIds we've already parsed to avoid double-counting
+  // (multiple session keys can share the same sessionId / .jsonl file)
+  const parsedTranscripts = new Map(); // sessionId -> transcript result
+  const countedSessionIds = new Set();
 
   for (const key of Object.keys(sessions)) {
     const s        = sessions[key];
@@ -515,31 +621,185 @@ function analyzeSessions(sessionsPath) {
     const modelKey = resolveModel(model);
     const inTok    = s.inputTokens  || s.tokensIn  || s.tokens?.input  || 0;
     const outTok   = s.outputTokens || s.tokensOut || s.tokens?.output || 0;
-    const cost     = costPerCall(modelKey, inTok, outTok);
+    const estimatedCost = costPerCall(modelKey, inTok, outTok);
     const updatedAt = s.updatedAt || s.lastActive || null;
 
-    totalIn   += inTok;
-    totalOut  += outTok;
-    totalCost += cost;
+    // Look up transcript by sessionId (not by key name)
+    let transcript = null;
+    const sessionId = s.sessionId;
+    if (sessionsDir && sessionId) {
+      if (parsedTranscripts.has(sessionId)) {
+        transcript = parsedTranscripts.get(sessionId);
+      } else {
+        const jsonlPath = path.join(sessionsDir, `${sessionId}.jsonl`);
+        transcript = parseTranscript(jsonlPath);
+        parsedTranscripts.set(sessionId, transcript);
+      }
+    }
+
+    // Deduplicate: if multiple keys share a sessionId, only count transcript cost once
+    const isSharedSession = sessionId && countedSessionIds.has(sessionId);
+    if (sessionId) countedSessionIds.add(sessionId);
+
+    // Use transcript data when available, fall back to sessions.json estimates
+    let realIn, realOut, realCacheRead, realCacheWrite, realCost, realModel, realTotalTokens;
+    if (transcript && !isSharedSession) {
+      transcriptHits++;
+      realIn         = transcript.input;
+      realOut        = transcript.output;
+      realCacheRead  = transcript.cacheRead;
+      realCacheWrite = transcript.cacheWrite;
+      realCost       = transcript.totalCost;
+      realModel      = transcript.model || model;
+      realTotalTokens = transcript.totalTokens;
+    } else if (transcript && isSharedSession) {
+      // Shared sessionId — transcript already counted, show it but zero out cost
+      transcriptHits++;
+      realIn         = 0;
+      realOut        = 0;
+      realCacheRead  = 0;
+      realCacheWrite = 0;
+      realCost       = 0;
+      realModel      = transcript.model || model;
+      realTotalTokens = 0;
+    } else {
+      transcriptMisses++;
+      realIn         = inTok;
+      realOut        = outTok;
+      realCacheRead  = 0;
+      realCacheWrite = 0;
+      realCost       = estimatedCost;
+      realModel      = model;
+      realTotalTokens = inTok + outTok;
+    }
+
+    totalIn         += realIn;
+    totalOut        += realOut;
+    totalCacheRead  += realCacheRead;
+    totalCacheWrite += realCacheWrite;
+    totalCost       += estimatedCost;
+    totalRealCost   += realCost;
+
+    const allTokens = realTotalTokens || (realIn + realOut + realCacheRead + realCacheWrite);
 
     const isOrphaned = key.includes('cron') || key.includes('deleted') ||
       (updatedAt && Date.now() - new Date(updatedAt).getTime() > 48 * 3600 * 1000 && !key.includes('main'));
 
-    if (isOrphaned) orphaned.push({ key, model, tokens: inTok + outTok, cost });
-    if (inTok + outTok > 50000) large.push({ key, model, tokens: inTok + outTok });
+    if (isOrphaned) orphaned.push({ key, model: realModel, tokens: allTokens, cost: realCost });
+    if (allTokens > 50000) large.push({ key, model: realModel, tokens: allTokens });
 
     const ageMs    = updatedAt ? Date.now() - new Date(updatedAt).getTime() : null;
     const ageDays  = ageMs ? ageMs / (1000 * 3600 * 24) : null;
-    const dailyCost = (ageDays && ageDays > 0.01 && cost > 0) ? cost / ageDays : null;
+    const dailyCost = (ageDays && ageDays > 0.01 && realCost > 0) ? realCost / ageDays : null;
+
+    const realModelKey = resolveModel(realModel);
+    breakdown.push({
+      key, sessionId: sessionId || null, model: realModel,
+      modelLabel: realModelKey ? (MODEL_PRICING[realModelKey]?.label || realModelKey) : (modelKey ? (MODEL_PRICING[modelKey]?.label || modelKey) : 'unknown'),
+      inputTokens: realIn, outputTokens: realOut,
+      cacheRead: realCacheRead, cacheWrite: realCacheWrite,
+      cost: realCost, estimatedCost,
+      hasTranscript: !!transcript,
+      isSharedSession,
+      messageCount: transcript?.messageCount || 0,
+      updatedAt, ageMs, dailyCost, isOrphaned,
+    });
+  }
 
-    breakdown.push({ key, model, modelLabel: modelKey ? (MODEL_PRICING[modelKey]?.label || modelKey) : 'unknown', inputTokens: inTok, outputTokens: outTok, cost, updatedAt, ageMs, dailyCost, isOrphaned });
+  // Scan for untracked .jsonl files (sessions not in sessions.json)
+  const trackedIds = new Set(Object.values(sessions).map(s => s.sessionId).filter(Boolean));
+  let untrackedCount = 0, untrackedCost = 0, untrackedTokens = 0;
+  if (sessionsDir) {
+    try {
+      for (const file of fs.readdirSync(sessionsDir)) {
+        if (!file.endsWith('.jsonl')) continue;
+        const fileId = file.replace('.jsonl', '');
+        if (trackedIds.has(fileId)) continue; // already counted
+        const transcript = parseTranscript(path.join(sessionsDir, file));
+        if (transcript && transcript.messageCount > 0) {
+          untrackedCount++;
+          untrackedCost += transcript.totalCost;
+          untrackedTokens += transcript.totalTokens;
+          totalRealCost += transcript.totalCost;
+          totalCacheRead += transcript.cacheRead;
+          totalCacheWrite += transcript.cacheWrite;
+          breakdown.push({
+            key: `untracked:${fileId.slice(0, 8)}`, sessionId: fileId, model: transcript.model,
+            modelLabel: transcript.model ? (MODEL_PRICING[resolveModel(transcript.model)]?.label || transcript.model) : 'unknown',
+            inputTokens: transcript.input, outputTokens: transcript.output,
+            cacheRead: transcript.cacheRead, cacheWrite: transcript.cacheWrite,
+            cost: transcript.totalCost, estimatedCost: 0,
+            hasTranscript: true, isSharedSession: false,
+            messageCount: transcript.messageCount,
+            updatedAt: transcript.lastTs ? new Date(transcript.lastTs).toISOString() : null,
+            ageMs: transcript.lastTs ? Date.now() - transcript.lastTs : null,
+            dailyCost: null, isOrphaned: false, isUntracked: true,
+          });
+        }
+      }
+    } catch { /* can't read dir */ }
   }
 
+  if (untrackedCount > 0) {
+    findings.push({
+      severity: untrackedCost > 1 ? 'high' : 'medium',
+      source: 'sessions',
+      message: `${untrackedCount} untracked session(s) found — .jsonl files not in sessions.json`,
+      detail: `${untrackedTokens.toLocaleString()} tokens · $${untrackedCost.toFixed(4)} in API costs\nThese are old/deleted sessions still on disk with real spend data`,
+    });
+  }
+
+  // Findings
   if (orphaned.length > 0) findings.push({ severity: 'high', source: 'sessions', message: `${orphaned.length} orphaned session(s) — still holding tokens on paid models`, detail: orphaned.map(s => `${s.key}: ${s.tokens.toLocaleString()} tokens ($${s.cost.toFixed(4)})`).join('\n  '), ...FIXES.ORPHANED_SESSIONS });
   if (large.length > 0) findings.push({ severity: 'medium', source: 'sessions', message: `${large.length} session(s) with >50k tokens per conversation`, detail: large.map(s => `${s.key}: ${s.tokens.toLocaleString()} tokens`).join('\n  '), ...FIXES.LARGE_SESSIONS });
   if (Object.keys(sessions).length > 0 && !orphaned.length && !large.length) findings.push({ severity: 'info', source: 'sessions', message: `${Object.keys(sessions).length} session(s) healthy ✓`, detail: `Total tokens: ${(totalIn + totalOut).toLocaleString()}` });
 
-  return { exists: true, findings, sessions: breakdown, totalInputTokens: totalIn, totalOutputTokens: totalOut, totalCost, sessionCount: Object.keys(sessions).length };
+  // Cache cost finding
+  if (totalCacheWrite > 0 || totalCacheRead > 0) {
+    const cacheDetail = [];
+    if (totalCacheRead > 0)  cacheDetail.push(`Cache reads: ${totalCacheRead.toLocaleString()} tokens`);
+    if (totalCacheWrite > 0) cacheDetail.push(`Cache writes: ${totalCacheWrite.toLocaleString()} tokens`);
+    const cacheCostPortion = totalRealCost - totalCost;
+    if (cacheCostPortion > 0.01) {
+      findings.push({
+        severity: cacheCostPortion > 1 ? 'high' : 'medium',
+        source: 'sessions',
+        message: `Prompt caching added $${cacheCostPortion.toFixed(4)} beyond base token costs`,
+        detail: cacheDetail.join('\n  ') + `\n  Cache writes are 3.75x input cost · Cache reads are 0.1x input cost`,
+        monthlyCost: 0, // already counted in session costs, not a recurring config bleed
+      });
+    } else {
+      findings.push({ severity: 'info', source: 'sessions', message: `Prompt caching active — ${(totalCacheRead + totalCacheWrite).toLocaleString()} cache tokens tracked`, detail: cacheDetail.join(' · ') });
+    }
+  }
+
+  // Transcript coverage finding
+  if (transcriptHits > 0 || transcriptMisses > 0) {
+    const total = transcriptHits + transcriptMisses;
+    if (transcriptMisses > 0 && transcriptHits > 0) {
+      findings.push({ severity: 'info', source: 'sessions', message: `Transcript data: ${transcriptHits}/${total} sessions have .jsonl transcripts (${transcriptMisses} estimated)`, detail: `Sessions with transcripts show real API-reported costs including cache tokens` });
+    }
+  }
+
+  // Cost discrepancy finding
+  if (totalRealCost > 0 && totalCost > 0) {
+    const ratio = totalRealCost / totalCost;
+    if (ratio > 2) {
+      findings.push({
+        severity: 'high',
+        source: 'sessions',
+        message: `Real cost $${totalRealCost.toFixed(4)} is ${ratio.toFixed(1)}x higher than sessions.json estimate ($${totalCost.toFixed(4)})`,
+        detail: `sessions.json only tracks input/output tokens — cache tokens, which are the bulk of real spending, are only in .jsonl transcripts`,
+      });
+    }
+  }
+
+  return {
+    exists: true, findings, sessions: breakdown,
+    totalInputTokens: totalIn, totalOutputTokens: totalOut,
+    totalCost, totalCacheRead, totalCacheWrite, totalRealCost,
+    sessionCount: Object.keys(sessions).length,
+  };
 }
 
 // ── Workspace analysis ────────────────────────────────────────────
@@ -568,12 +828,64 @@ async function runAnalysis({ configPath, sessionsPath, logsDir }) {
   const sessionResult   = analyzeSessions(sessionsPath);
   const workspaceResult = analyzeWorkspace();
 
-  const allFindings = [...configResult.findings, ...sessionResult.findings, ...workspaceResult.findings];
+  // Scan additional agent folders beyond main
+  const agentDirs = discoverAgentDirs();
+  const additionalAgentSessions = [];
+  for (const { agent, sessionsDir } of agentDirs) {
+    const sjPath = path.join(sessionsDir, 'sessions.json');
+    // Skip the primary sessions path (already analyzed above)
+    if (sjPath === sessionsPath) continue;
+    if (fs.existsSync(sjPath)) {
+      const extra = analyzeSessions(sjPath);
+      if (extra.exists) {
+        additionalAgentSessions.push({ agent, ...extra });
+      }
+    }
+  }
+
+  // Scan web-chat sessions
+  const webChatPaths = discoverWebChatSessions();
+  const webChatSessions = [];
+  for (const wcp of webChatPaths) {
+    const transcript = parseTranscript(wcp);
+    if (transcript) {
+      const sessionId = path.basename(wcp, '.jsonl');
+      webChatSessions.push({ key: `web-chat/${sessionId}`, ...transcript });
+    }
+  }
+
+  // Merge all findings
+  const allFindings = [
+    ...configResult.findings,
+    ...sessionResult.findings,
+    ...workspaceResult.findings,
+  ];
+
+  // Add additional agent findings
+  for (const extra of additionalAgentSessions) {
+    if (extra.findings.length > 0) {
+      allFindings.push({ severity: 'info', source: 'sessions', message: `Agent "${extra.agent}": ${extra.sessionCount} session(s) found`, detail: `Tokens: ${(extra.totalInputTokens + extra.totalOutputTokens).toLocaleString()} · Cost: $${extra.totalRealCost.toFixed(4)}` });
+    }
+    // Merge their sessions into the main breakdown
+    sessionResult.sessions.push(...(extra.sessions || []));
+    sessionResult.totalRealCost += extra.totalRealCost || 0;
+    sessionResult.totalCacheRead += extra.totalCacheRead || 0;
+    sessionResult.totalCacheWrite += extra.totalCacheWrite || 0;
+  }
+
+  // Add web-chat finding if any
+  if (webChatSessions.length > 0) {
+    const wcTotal = webChatSessions.reduce((sum, s) => sum + s.totalCost, 0);
+    const wcTokens = webChatSessions.reduce((sum, s) => sum + s.totalTokens, 0);
+    allFindings.push({ severity: 'info', source: 'sessions', message: `${webChatSessions.length} web-chat session(s) found`, detail: `Tokens: ${wcTokens.toLocaleString()} · Cost: $${wcTotal.toFixed(4)}` });
+  }
 
   const estimatedMonthlyBleed = allFindings
     .filter(f => f.monthlyCost && f.severity !== 'info')
     .reduce((sum, f) => sum + f.monthlyCost, 0);
 
+  const realCost = sessionResult.totalRealCost || 0;
+
   return {
     scannedAt:    new Date().toISOString(),
     configPath,
@@ -589,10 +901,15 @@ async function runAnalysis({ configPath, sessionsPath, logsDir }) {
       estimatedMonthlyBleed,
       sessionsAnalyzed:      sessionResult.sessionCount,
       totalTokensFound:      (sessionResult.totalInputTokens || 0) + (sessionResult.totalOutputTokens || 0),
+      totalCacheRead:        sessionResult.totalCacheRead || 0,
+      totalCacheWrite:       sessionResult.totalCacheWrite || 0,
+      totalRealCost:         realCost,
+      totalEstimatedCost:    sessionResult.totalCost || 0,
     },
     sessions: sessionResult.sessions || [],
+    webChatSessions,
     config:   configResult.config,
   };
 }
 
-module.exports = { runAnalysis, MODEL_PRICING, resolveModel, costPerCall };
+module.exports = { runAnalysis, MODEL_PRICING, resolveModel, costPerCall, parseTranscript, discoverAgentDirs, discoverWebChatSessions };

package/src/clawculator.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+const { runAnalysis } = require('../src/analyzer');
+const { generateTerminalReport } = require('../src/reporter');
+const { generateMarkdownReport } = require('../src/mdReport');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+const args = process.argv.slice(2);
+const flags = {
+  report: args.includes('--report'),
+  json:   args.includes('--json'),
+  md:     args.includes('--md'),
+  help:   args.includes('--help') || args.includes('-h'),
+  config: args.find(a => a.startsWith('--config='))?.split('=')[1],
+  out:    args.find(a => a.startsWith('--out='))?.split('=')[1],
+};
+
+const BANNER = `
+\x1b[36m
+   ██████╗██╗      █████╗ ██╗    ██╗ ██████╗ █████╗ ██╗      ██████╗
+  ██╔════╝██║     ██╔══██╗██║    ██║██╔════╝██╔══██╗██║     ██╔════╝
+  ██║     ██║     ███████║██║ █╗ ██║██║     ███████║██║     ██║     
+  ██║     ██║     ██╔══██║██║███╗██║██║     ██╔══██║██║     ██║     
+  ╚██████╗███████╗██║  ██║╚███╔███╔╝╚██████╗██║  ██║███████╗╚██████╗
+   ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝  ╚═════╝╚═╝  ╚═╝╚══════╝ ╚═════╝
+\x1b[0m
+  \x1b[33mYour friendly penny pincher.\x1b[0m
+  \x1b[90m100% offline · Zero AI · Pure deterministic logic · Your data never leaves your machine\x1b[0m
+`;
+
+const HELP = `
+Usage: clawculator [options]
+
+Options:
+  (no flags)        Full terminal analysis
+  --md              Save markdown report to ./clawculator-report.md
+  --report          Generate HTML report and open in browser
+  --json            Output raw JSON
+  --out=PATH        Custom output path for --md or --report
+  --config=PATH     Path to openclaw.json (auto-detected by default)
+  --help, -h        Show this help
+
+Examples:
+  npx clawculator                         # Terminal analysis
+  npx clawculator --md                    # Markdown report (readable by your AI agent)
+  npx clawculator --report                # Visual HTML dashboard
+  npx clawculator --json                  # JSON for piping
+  npx clawculator --md --out=~/cost.md    # Custom path
+`;
+
+async function main() {
+  if (flags.help) {
+    console.log(BANNER);
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  console.log(BANNER);
+  console.log('\x1b[90mScanning your setup...\x1b[0m\n');
+
+  const openclawHome = process.env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw');
+  const configPath   = flags.config || path.join(openclawHome, 'openclaw.json');
+
+  // Auto-discover sessions path: find first agent with a sessions.json
+  let sessionsPath = path.join(openclawHome, 'agents', 'main', 'sessions', 'sessions.json');
+  if (!fs.existsSync(sessionsPath)) {
+    const agentsDir = path.join(openclawHome, 'agents');
+    try {
+      for (const agent of fs.readdirSync(agentsDir)) {
+        const candidate = path.join(agentsDir, agent, 'sessions', 'sessions.json');
+        if (fs.existsSync(candidate)) { sessionsPath = candidate; break; }
+      }
+    } catch { /* agents dir missing */ }
+  }
+
+  const logsDir      = '/tmp/openclaw';
+
+  let analysis;
+  try {
+    analysis = await runAnalysis({ configPath, sessionsPath, logsDir });
+  } catch (err) {
+    console.error('\x1b[31mError:\x1b[0m', err.message);
+    process.exit(1);
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(analysis, null, 2));
+    process.exit(0);
+  }
+
+  if (flags.md) {
+    const outPath = flags.out || path.join(process.cwd(), 'clawculator-report.md');
+    fs.writeFileSync(outPath, generateMarkdownReport(analysis), 'utf8');
+    console.log(`\x1b[32m✓ Markdown report saved:\x1b[0m ${outPath}`);
+    generateTerminalReport(analysis);
+    process.exit(0);
+  }
+
+  if (flags.report) {
+    const outPath = flags.out || path.join(process.cwd(), `clawculator-report.html`);
+    const { generateHTMLReport } = require('../src/htmlReport');
+    await generateHTMLReport(analysis, outPath);
+    const { exec } = require('child_process');
+    exec(`open "${outPath}" 2>/dev/null || xdg-open "${outPath}" 2>/dev/null`);
+    console.log(`\x1b[32m✓ HTML report saved:\x1b[0m ${outPath}`);
+    generateTerminalReport(analysis);
+    process.exit(0);
+  }
+
+  generateTerminalReport(analysis);
+  console.log('\x1b[90m────────────────────────────────────────────────────\x1b[0m');
+  console.log('\x1b[36mClawculator\x1b[0m · github.com/echoudhry/clawculator · Your friendly penny pincher.');
+  console.log('\x1b[90mTip: --md saves a report your AI agent can read directly\x1b[0m');
+  console.log('\x1b[90m────────────────────────────────────────────────────\x1b[0m\n');
+}
+
+main().catch(err => {
+  console.error('\x1b[31mFatal:\x1b[0m', err.message);
+  process.exit(1);
+});

package/src/htmlReport.js

@@ -79,14 +79,16 @@ async function generateHTMLReport(analysis, outPath) {
     .map(s => {
       const keyDisplay = s.key.length > 12 ? s.key.slice(0, 8) + '…' : s.key;
       const flag = s.isOrphaned ? ' ⚠️' : '';
+      const txBadge = s.hasTranscript ? '<span style="color:#22c55e; font-size:10px; margin-left:4px" title="Cost from .jsonl transcript (API-reported)">●</span>' : '<span style="color:#6b7280; font-size:10px; margin-left:4px" title="Estimated cost (no transcript found)">○</span>';
       const age = s.ageMs ? relativeAge(s.ageMs) : 'unknown';
       const absDate = s.updatedAt ? new Date(s.updatedAt).toLocaleString() : '';
       const daily = s.dailyCost ? `$${s.dailyCost.toFixed(4)}/day` : '—';
+      const cacheTitle = (s.cacheRead || s.cacheWrite) ? `Cache R: ${(s.cacheRead||0).toLocaleString()} · W: ${(s.cacheWrite||0).toLocaleString()}` : '';
       return `
       <tr style="${s.isOrphaned ? 'background:#fff7ed' : ''}">
-        <td style="padding:8px 12px; font-family:monospace; font-size:13px">${keyDisplay}${flag}</td>
+        <td style="padding:8px 12px; font-family:monospace; font-size:13px">${keyDisplay}${flag}${txBadge}</td>
         <td style="padding:8px 12px">${s.modelLabel || s.model}</td>
-        <td style="padding:8px 12px; text-align:right">${(s.inputTokens + s.outputTokens).toLocaleString()}</td>
+        <td style="padding:8px 12px; text-align:right" title="${cacheTitle}">${(s.inputTokens + s.outputTokens).toLocaleString()}${(s.cacheRead || s.cacheWrite) ? `<span style="color:#6b7280; font-size:11px;"> +${((s.cacheRead||0)+(s.cacheWrite||0)).toLocaleString()} cache</span>` : ''}</td>
         <td style="padding:8px 12px; text-align:right; color:${s.cost > 0.01 ? '#ef4444' : '#22c55e'}">$${s.cost.toFixed(6)}</td>
         <td style="padding:8px 12px; text-align:right; color:#f59e0b">${daily}</td>
         <td style="padding:8px 12px; color:#6b7280; font-size:13px" title="${absDate}">${age}</td>
@@ -138,6 +140,27 @@ async function generateHTMLReport(analysis, outPath) {
       <div style="color:#86efac; font-size:18px; font-weight:700">✅ No significant cost bleed detected</div>
     </div>`}
 
+    ${summary.totalRealCost > 0 ? `
+    <div class="section" style="border:1px solid #f59e0b;">
+      <div class="section-title" style="color:#f59e0b;">💰 Actual API Spend (from transcripts)</div>
+      <div style="display:flex; gap:32px; flex-wrap:wrap; align-items:center;">
+        <div>
+          <div style="font-size:36px; font-weight:900; color:#fbbf24;">$${summary.totalRealCost.toFixed(4)}</div>
+          <div style="font-size:13px; color:#94a3b8; margin-top:4px;">Total real cost (API-reported)</div>
+        </div>
+        ${summary.totalEstimatedCost > 0 && summary.totalRealCost > summary.totalEstimatedCost * 1.1 ? `
+        <div style="background:#451a03; padding:10px 16px; border-radius:8px; border:1px solid #92400e;">
+          <div style="font-size:14px; color:#fbbf24; font-weight:600;">${(summary.totalRealCost / summary.totalEstimatedCost).toFixed(1)}x higher than sessions.json estimate</div>
+          <div style="font-size:12px; color:#d97706; margin-top:2px;">sessions.json: $${summary.totalEstimatedCost.toFixed(4)} — missing cache token costs</div>
+        </div>` : ''}
+      </div>
+      ${summary.totalCacheRead > 0 || summary.totalCacheWrite > 0 ? `
+      <div style="margin-top:16px; display:flex; gap:24px; flex-wrap:wrap;">
+        ${summary.totalCacheWrite > 0 ? `<div style="color:#f97316; font-size:14px;">📝 Cache writes: <strong>${summary.totalCacheWrite.toLocaleString()}</strong> tokens</div>` : ''}
+        ${summary.totalCacheRead > 0 ? `<div style="color:#22c55e; font-size:14px;">📖 Cache reads: <strong>${summary.totalCacheRead.toLocaleString()}</strong> tokens</div>` : ''}
+      </div>` : ''}
+    </div>` : ''}
+
     <div class="cards">
       <div class="card">
         <div class="card-value" style="color:#ef4444">${summary.critical}</div>

package/src/mdReport.js

@@ -69,6 +69,14 @@ function generateMarkdownReport(analysis) {
     if (totalCost > 0)      lines.push(`| Total session cost (lifetime) | $${totalCost.toFixed(4)} |`);
     if (totalDailyRate > 0) lines.push(`| Avg daily burn rate | $${totalDailyRate.toFixed(4)}/day (~$${(totalDailyRate * 30).toFixed(2)}/month) |`);
   }
+  if (summary.totalRealCost > 0) {
+    lines.push(`| 💰 **Actual API spend** | **$${summary.totalRealCost.toFixed(4)}** |`);
+    if (summary.totalEstimatedCost > 0 && summary.totalRealCost > summary.totalEstimatedCost * 1.1) {
+      lines.push(`| sessions.json estimate | $${summary.totalEstimatedCost.toFixed(4)} (${(summary.totalRealCost / summary.totalEstimatedCost).toFixed(1)}x gap) |`);
+    }
+  }
+  if (summary.totalCacheWrite > 0) lines.push(`| Cache writes | ${summary.totalCacheWrite.toLocaleString()} tokens |`);
+  if (summary.totalCacheRead > 0)  lines.push(`| Cache reads | ${summary.totalCacheRead.toLocaleString()} tokens |`);
   lines.push('');
 
   // Findings by severity

package/src/reporter.js

@@ -115,6 +115,15 @@ function generateTerminalReport(analysis) {
   console.log(`${C}━━━ Summary ━━━${R}`);
   console.log(`  🔴 ${RED}${summary.critical}${R} critical  🟠 ${summary.high} high  🟡 ${summary.medium} medium  🔵 ${summary.low||0} low  ✅ ${summary.info} ok`);
   console.log(`  Sessions analyzed: ${summary.sessionsAnalyzed} · Tokens found: ${(summary.totalTokensFound||0).toLocaleString()}`);
+  if (summary.totalCacheRead > 0 || summary.totalCacheWrite > 0) {
+    console.log(`  ${D}Cache tokens: ${(summary.totalCacheRead||0).toLocaleString()} read · ${(summary.totalCacheWrite||0).toLocaleString()} write${R}`);
+  }
+  if (summary.totalRealCost > 0) {
+    console.log(`  ${B}Actual API spend: ${RED}$${summary.totalRealCost.toFixed(4)}${R}${B} (from .jsonl transcripts)${R}`);
+    if (summary.totalEstimatedCost > 0 && summary.totalRealCost > summary.totalEstimatedCost * 1.1) {
+      console.log(`  ${D}sessions.json estimate: $${summary.totalEstimatedCost.toFixed(4)} — ${(summary.totalRealCost / summary.totalEstimatedCost).toFixed(1)}x gap (cache tokens)${R}`);
+    }
+  }
   if (bleed > 0) {
     console.log(`  ${RED}${B}Estimated monthly bleed: $${bleed.toFixed(2)}/month${R}`);
   } else {