cchubber 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cchubber",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "What you spent. Why you spent it. Is that normal. — Claude Code usage diagnosis with beautiful HTML reports.",
   "type": "module",
   "bin": {

package/src/analyzers/cache-health.js

@@ -57,13 +57,20 @@ export function analyzeCacheHealth(statsCache, cacheBreaks, days, dailyFromJSONL
   // With cache: reads are $0.50/M
   const savingsFromCache = totalCacheRead / 1_000_000 * (5.0 - 0.50);
 
-  // Cost wasted from cache breaks (rough estimate)
-  // Each cache break forces a full re-read at write price ($6.25/M) instead of read price ($0.50/M)
-  // Estimate ~200K tokens re-cached per break
-  const wastedFromBreaks = totalBreaks * 200_000 / 1_000_000 * (6.25 - 0.50);
+  // Cost wasted from cache rewrites
+  // Cache writes happen when cache is invalidated — costs 12.5x more than reads
+  // Use actual cache write tokens as the signal (more reliable than diff file count)
+  const wastedFromBreaks = totalBreaks > 0
+    ? totalBreaks * 200_000 / 1_000_000 * (6.25 - 0.50)
+    : totalCacheWrite / 1_000_000 * (6.25 - 0.50); // estimate from write tokens
+
+  // If no diff files but cache writes exist, estimate break count
+  // Each break re-caches ~200K-500K tokens on average
+  const estimatedBreaks = totalBreaks > 0 ? totalBreaks : Math.round(totalCacheWrite / 300_000);
 
   return {
     totalCacheBreaks: totalBreaks,
+    estimatedBreaks,
     reasonsRanked,
     cacheHitRate: Math.round(cacheHitRate * 10) / 10,
     efficiencyRatio,

package/src/analyzers/inflection-detector.js

@@ -1,7 +1,7 @@
 /**
  * Inflection Point Detection
- * Finds the sharpest change in cache efficiency ratio over time.
- * Outputs: "Your efficiency dropped 3.6x starting March 29. Before: 482:1. After: 1,726:1."
+ * Finds BOTH the worst degradation AND best improvement in cache efficiency.
+ * Prioritizes degradation — that's what users care about ("why is my usage draining?").
  */
 export function detectInflectionPoints(dailyFromJSONL) {
   if (!dailyFromJSONL || dailyFromJSONL.length < 5) return null;
@@ -12,10 +12,10 @@ export function detectInflectionPoints(dailyFromJSONL) {
 
   if (sorted.length < 5) return null;
 
-  // Sliding window: compare the average ratio of days before vs after each point
-  // Window size: at least 3 days on each side
   const minWindow = 3;
-  let bestSplit = null;
+  let worstDegradation = null;
+  let worstScore = 0;
+  let bestImprovement = null;
   let bestScore = 0;
 
   for (let i = minWindow; i <= sorted.length - minWindow; i++) {
@@ -27,32 +27,44 @@ export function detectInflectionPoints(dailyFromJSONL) {
 
     if (beforeRatio === 0 || afterRatio === 0) continue;
 
-    // Score = magnitude of change (either direction)
-    const changeMultiplier = afterRatio > beforeRatio
-      ? afterRatio / beforeRatio
-      : beforeRatio / afterRatio;
-
-    if (changeMultiplier > bestScore && changeMultiplier >= 1.5) {
-      bestScore = changeMultiplier;
-      bestSplit = {
-        date: sorted[i].date,
-        beforeRatio,
-        afterRatio,
-        multiplier: Math.round(changeMultiplier * 10) / 10,
-        direction: afterRatio > beforeRatio ? 'worsened' : 'improved',
-        beforeDays: before.length,
-        afterDays: after.length,
-      };
+    if (afterRatio > beforeRatio) {
+      // Degradation (ratio went UP = worse)
+      const mult = afterRatio / beforeRatio;
+      if (mult > worstScore && mult >= 1.5) {
+        worstScore = mult;
+        worstDegradation = buildResult(sorted[i].date, beforeRatio, afterRatio, mult, 'worsened', before.length, after.length);
+      }
+    } else {
+      // Improvement (ratio went DOWN = better)
+      const mult = beforeRatio / afterRatio;
+      if (mult > bestScore && mult >= 1.5) {
+        bestScore = mult;
+        bestImprovement = buildResult(sorted[i].date, beforeRatio, afterRatio, mult, 'improved', before.length, after.length);
+      }
     }
   }
 
-  if (!bestSplit) return null;
+  // Return degradation as primary (that's the problem), improvement as secondary
+  const primary = worstDegradation || bestImprovement;
+  if (!primary) return null;
 
-  // Build human-readable summary
-  const dirLabel = bestSplit.direction === 'worsened' ? 'dropped' : 'improved';
-  bestSplit.summary = `Your cache efficiency ${dirLabel} ${bestSplit.multiplier}x starting ${formatDate(bestSplit.date)}. Before: ${bestSplit.beforeRatio.toLocaleString()}:1. After: ${bestSplit.afterRatio.toLocaleString()}:1.`;
+  primary.secondary = worstDegradation ? bestImprovement : null;
+  return primary;
+}
 
-  return bestSplit;
+function buildResult(date, beforeRatio, afterRatio, multiplier, direction, beforeDays, afterDays) {
+  const mult = Math.round(multiplier * 10) / 10;
+  const dirLabel = direction === 'worsened' ? 'dropped' : 'improved';
+  return {
+    date,
+    beforeRatio,
+    afterRatio,
+    multiplier: mult,
+    direction,
+    beforeDays,
+    afterDays,
+    summary: `Your cache efficiency ${dirLabel} ${mult}x starting ${formatDate(date)}. Before: ${beforeRatio.toLocaleString()}:1. After: ${afterRatio.toLocaleString()}:1.`,
+  };
 }
 
 function computeRatio(days) {

package/src/analyzers/recommendations.js

@@ -1,117 +1,111 @@
 /**
  * Recommendations Engine
- * Generates actionable recommendations informed by community data (March 2026 crisis).
- * Every recommendation maps to a real pattern reported by users on GitHub/Twitter/Reddit.
+ * Each recommendation includes estimated usage % savings.
+ * Informed by community data from the March 2026 Claude Code crisis.
  */
 export function generateRecommendations(costAnalysis, cacheHealth, claudeMdStack, anomalies, inflection, sessionIntel, modelRouting) {
   const recs = [];
+  const totalCost = costAnalysis.totalCost || 1;
 
-  // 0. Inflection point — most important signal
+  // 0. Inflection point
   if (inflection && inflection.direction === 'worsened' && inflection.multiplier >= 2) {
     recs.push({
       severity: 'critical',
       title: `Cache efficiency dropped ${inflection.multiplier}x on ${inflection.date}`,
-      detail: inflection.summary,
-      action: 'Run: claude update. Versions 2.1.69-2.1.89 had a cache sentinel bug that dropped read rates from 95% to 4-17%. Fixed in v2.1.90.',
+      savings: '~40-60% usage reduction after fix',
+      action: 'Run: claude update. v2.1.69-2.1.89 had cache bugs. Fixed in v2.1.90.',
     });
   } else if (inflection && inflection.direction === 'improved' && inflection.multiplier >= 2) {
     recs.push({
       severity: 'positive',
       title: `Efficiency improved ${inflection.multiplier}x on ${inflection.date}`,
-      detail: inflection.summary,
-      action: 'Your cache efficiency improved here. Likely a version update or workflow change that stuck.',
+      savings: 'Already saving',
+      action: 'Your cache efficiency improved. Likely a version update or workflow change.',
     });
   }
 
-  // 1. CLAUDE.md bloat — community-reported 10-20x cost multiplier
-  if (claudeMdStack.totalTokensEstimate > 8000) {
-    const dailyCost = claudeMdStack.costPerMessage?.dailyCached200;
-    recs.push({
-      severity: claudeMdStack.totalTokensEstimate > 15000 ? 'critical' : 'warning',
-      title: `CLAUDE.md is ${Math.round(claudeMdStack.totalTokensEstimate / 1000)}K tokens`,
-      detail: `Re-read on every turn. Community best practice: keep under 200 lines (~4K tokens). Yours costs ~$${dailyCost ? dailyCost.toFixed(2) : '?'}/day at 200 messages. Each cache break re-reads at 12.5x the cached price.`,
-      action: 'Move rarely-used rules to project-level files. Use skills/hooks instead of inline instructions. Every 1K tokens removed saves ~$0.50/day.',
-    });
-  }
+  // 1. Model routing — biggest actionable saving for most users
+  const modelCosts = costAnalysis.modelCosts || {};
+  const totalModelCost = Object.values(modelCosts).reduce((s, c) => s + c, 0);
+  const opusCost = Object.entries(modelCosts).filter(([n]) => n.toLowerCase().includes('opus')).reduce((s, [, c]) => s + c, 0);
+  const opusPct = totalModelCost > 0 ? Math.round((opusCost / totalModelCost) * 100) : 0;
 
-  // 2. Version check — the #1 fix reported by community
-  if (cacheHealth.efficiencyRatio > 1500 || (inflection && inflection.direction === 'worsened')) {
+  if (opusPct > 80) {
+    const savingsPct = Math.round(opusPct * 0.4 * 0.8); // 40% of Opus routable, 80% cheaper
     recs.push({
-      severity: 'critical',
-      title: 'Update Claude Code to v2.1.90+',
-      detail: 'Versions 2.1.69-2.1.89 had three cache bugs: sentinel replacement error, --resume cache miss, and nested CLAUDE.md re-injection. Community-verified: usage dropped from 80-100% to 5-7% of Max quota after updating.',
-      action: 'Run: claude update. If already on latest, start a fresh session — the fix only applies to new sessions.',
+      severity: 'warning',
+      title: `${opusPct}% usage is Opus — route subagents to Sonnet`,
+      savings: `~${savingsPct}% usage reduction`,
+      action: `Set model: "sonnet" on Task/subagent calls. Sonnet handles search, file reads, docs, and simple edits at same quality. Community-verified: limits lasted 3-5x longer.`,
     });
   }
 
-  // 3. Cache break analysis
-  if (cacheHealth.totalCacheBreaks > 10) {
-    const topReason = cacheHealth.reasonsRanked[0];
+  // 2. CLAUDE.md bloat
+  if (claudeMdStack.totalTokensEstimate > 8000) {
+    const excessK = Math.round((claudeMdStack.totalTokensEstimate - 4000) / 1000);
     recs.push({
-      severity: cacheHealth.totalCacheBreaks > 50 ? 'critical' : 'warning',
-      title: `${cacheHealth.totalCacheBreaks} cache invalidations`,
-      detail: `Each break forces a full prompt re-read at write prices (12.5x cache read cost). ${topReason ? `Top cause: "${topReason.reason}" (${topReason.count}x, ${topReason.percentage}%).` : ''}`,
-      action: topReason?.reason === 'Tool schemas changed'
-        ? 'Reduce MCP server connections. Each tool schema change breaks the cache prefix. Disconnect tools you\'re not actively using.'
-        : topReason?.reason === 'System prompt changed'
-        ? 'Stop editing CLAUDE.md mid-session. Batch rule changes between sessions.'
-        : 'Review ~/.claude/tmp/cache-break-*.diff for exact invalidation causes.',
+      severity: claudeMdStack.totalTokensEstimate > 15000 ? 'critical' : 'warning',
+      title: `CLAUDE.md is ${Math.round(claudeMdStack.totalTokensEstimate / 1000)}K tokens — trim to <4K`,
+      savings: `saves ~${excessK}K tokens/msg`,
+      action: 'Re-read on every turn. Move rarely-used rules to project files. Use skills/hooks instead of inline instructions. Community target: under 200 lines.',
     });
   }
 
-  // 4. High cache:output ratio
-  if (cacheHealth.efficiencyRatio > 2000) {
-    recs.push({
-      severity: 'critical',
-      title: `Cache ratio ${cacheHealth.efficiencyRatio.toLocaleString()}:1 — abnormally high`,
-      detail: `Healthy range: 300-800:1. You\'re at ${cacheHealth.efficiencyRatio.toLocaleString()}:1 — every output token costs ${cacheHealth.efficiencyRatio.toLocaleString()} cache read tokens. This pattern matches the March 2026 cache bug reported by thousands of users.`,
-      action: 'Immediate fix: update to v2.1.90+. If already updated, avoid --resume flag and start fresh sessions per task.',
-    });
-  } else if (cacheHealth.efficiencyRatio > 1000) {
+  // 3. Compaction frequency — community's #1 session management tip
+  if (sessionIntel?.available && sessionIntel.avgToolsPerSession > 25) {
     recs.push({
       severity: 'warning',
-      title: `Cache ratio ${cacheHealth.efficiencyRatio.toLocaleString()}:1 — elevated`,
-      detail: 'Not critical, but above the 300-800 healthy range. Common causes: large codebase exploration, many file reads without /compact, or stale sessions.',
-      action: 'Use /compact every 30-40 tool calls. Start fresh sessions for each distinct task.',
+      title: `Avg ${sessionIntel.avgToolsPerSession} tool calls/session — compact more often`,
+      savings: '~15-25% usage reduction',
+      action: 'Use /compact every 30-40 tool calls. Context bloat compounds — each message re-reads the full history. Community tip: compacting at 40 calls saves 20%+ on long sessions.',
     });
   }
 
-  // 5. Opus dominance — community tip: Sonnet handles 60%+ of tasks at 1/5 cost
-  const modelCosts = costAnalysis.modelCosts || {};
-  const totalModelCost = Object.values(modelCosts).reduce((s, c) => s + c, 0);
-  const opusCost = Object.entries(modelCosts).filter(([n]) => n.toLowerCase().includes('opus')).reduce((s, [, c]) => s + c, 0);
-  const opusPct = totalModelCost > 0 ? Math.round((opusCost / totalModelCost) * 100) : 0;
-
-  if (opusPct > 85) {
-    const savings = modelRouting?.estimatedSavings || Math.round(opusCost * 0.16);
+  // 4. Fresh sessions per task
+  if (sessionIntel?.available && sessionIntel.longSessionPct > 30) {
     recs.push({
       severity: 'warning',
-      title: `${opusPct}% of spend is Opus`,
-      detail: `Opus costs 5x more than Sonnet per token. Sonnet 4.6 handles file reads, search, simple edits, and subagent work at the same quality. Community tip: switching routine tasks to Sonnet dropped quota usage by 60-80%.`,
-      action: `Set model: "sonnet" on subagent/Task calls. Estimated savings: ~$${savings.toLocaleString()}. Reserve Opus for complex reasoning only.`,
+      title: `${sessionIntel.longSessionPct}% of sessions over 60 min — start fresh more often`,
+      savings: '~10-20% usage reduction',
+      action: `One task, one session. Your p90 is ${sessionIntel.p90Duration}min, longest ${sessionIntel.maxDuration}min. Starting fresh resets context and maximizes cache hits. Cheaper than a bloated session.`,
     });
   }
 
-  // 6. Session length — community-reported: sessions >60 min degrade heavily
-  if (sessionIntel?.available && sessionIntel.longSessionPct > 30) {
+  // 5. Cache ratio warning
+  if (cacheHealth.efficiencyRatio > 1500) {
     recs.push({
-      severity: 'warning',
-      title: `${sessionIntel.longSessionPct}% of sessions exceed 60 minutes`,
-      detail: `Long sessions accumulate context that degrades cache efficiency and response quality. Your median: ${sessionIntel.medianDuration}min, p90: ${sessionIntel.p90Duration}min, longest: ${sessionIntel.maxDuration}min.`,
-      action: 'One task, one session. Use /compact for exploration, fresh session for each bug fix or feature. The cost of starting fresh is less than the cost of a bloated context.',
+      severity: 'critical',
+      title: `Cache ratio ${cacheHealth.efficiencyRatio.toLocaleString()}:1 — update Claude Code`,
+      savings: '~40-60% usage reduction',
+      action: 'Run: claude update. v2.1.89 had cache bugs that inflated ratios 10-20x. Community-verified: v2.1.90 dropped usage from 80-100% to 5-7% of Max quota.',
+    });
+  } else if (cacheHealth.efficiencyRatio > 800) {
+    recs.push({
+      severity: 'info',
+      title: `Cache ratio ${cacheHealth.efficiencyRatio.toLocaleString()}:1 — slightly elevated`,
+      savings: '~5-10% with optimization',
+      action: 'Healthy range: 300-800:1. Reduce by compacting more often, starting fresh sessions, and avoiding --resume on older CC versions.',
     });
   }
 
-  // 7. Peak hour overlap — community-reported: 5am-11am PT has throttled limits
+  // 6. Peak hour overlap
   if (sessionIntel?.available && sessionIntel.peakOverlapPct > 40) {
     recs.push({
       severity: 'info',
-      title: `${sessionIntel.peakOverlapPct}% of your work hits throttled hours`,
-      detail: 'Anthropic reduces 5-hour session limits during weekday peak hours (5am-11am PT / 12pm-6pm UTC). ~7% of users hit limits they wouldn\'t otherwise.',
-      action: 'Shift token-heavy work (refactors, test generation, codebase exploration) to off-peak hours. Session limits are unchanged — only the 5-hour window shrinks.',
+      title: `${sessionIntel.peakOverlapPct}% of work during throttled hours`,
+      savings: '~30% longer session limits',
+      action: 'Anthropic throttles 5-hour limits during 5am-11am PT weekdays. Shift heavy work (refactors, test gen) to off-peak for 30%+ longer limits.',
     });
   }
 
+  // 7. .claudeignore — prevents reading node_modules etc
+  recs.push({
+    severity: 'info',
+    title: 'Create .claudeignore to exclude build artifacts',
+    savings: '~5-10% per context load',
+    action: 'Prevents CC from reading node_modules/, dist/, *.lock, __pycache__/. Each context load scans your project tree — excluding junk saves tokens every turn.',
+  });
+
   // 8. Cost anomalies
   if (anomalies.hasAnomalies) {
     const spikes = anomalies.anomalies.filter(a => a.type === 'spike');
@@ -119,23 +113,50 @@ export function generateRecommendations(costAnalysis, cacheHealth, claudeMdStack
       const worst = spikes[0];
       recs.push({
         severity: worst.severity,
-        title: `${spikes.length} cost spike${spikes.length > 1 ? 's' : ''} — worst: $${worst.cost.toFixed(0)} on ${worst.date}`,
-        detail: `+$${worst.deviation.toFixed(0)} above your $${worst.avgCost.toFixed(0)} daily average.${worst.cacheRatioAnomaly ? ' Cache ratio was also anomalous — strongly suggests cache bug.' : ''} GitHub #38029 documents a bug where a single session generated 652K phantom output tokens ($342).`,
-        action: 'Monitor the first 1-2 messages of each session. If a single message burns 3-5% of your quota, restart immediately.',
+        title: `${spikes.length} cost spike${spikes.length > 1 ? 's' : ''} — worst $${worst.cost.toFixed(0)} on ${worst.date}`,
+        savings: 'Preventable with monitoring',
+        action: 'Watch the first 1-2 messages of each session. If a single message burns 3-5% of quota, restart immediately. GitHub #38029 documents phantom 652K output token bugs.',
       });
     }
   }
 
-  // 9. Positive: cache savings
+  // 9. Avoid --resume on older versions
+  if (cacheHealth.efficiencyRatio > 600) {
+    recs.push({
+      severity: 'info',
+      title: 'Avoid --resume and --continue flags',
+      savings: '~$0.15 saved per resume',
+      action: 'These flags caused full prompt-cache misses in v2.1.69-2.1.89 (~$0.15 per resume on 500K context). Fixed in v2.1.90. Copy your last message and start fresh instead.',
+    });
+  }
+
+  // 10. Specific prompt discipline
+  recs.push({
+    severity: 'info',
+    title: 'Be specific in prompts — reduces tokens up to 10x',
+    savings: '~20-40% usage reduction',
+    action: 'Instead of "fix the auth bug", say "fix JWT validation in src/auth/validate.ts line 42". Specific prompts avoid codebase-wide scans. Community-verified: 10x reduction per prompt.',
+  });
+
+  // 11. Disconnect unused MCP tools
+  if (sessionIntel?.available && sessionIntel.topTools.some(t => t.name.includes('mcp__'))) {
+    recs.push({
+      severity: 'info',
+      title: 'Disconnect unused MCP servers',
+      savings: '~5-15% per cache break avoided',
+      action: 'Each MCP tool schema change invalidates the prompt cache. Only connect servers you actively need. Disconnect the rest between sessions.',
+    });
+  }
+
+  // 12. Cache savings (positive)
   if (cacheHealth.savings?.fromCaching > 100) {
     recs.push({
       severity: 'positive',
-      title: `Cache saved you ~$${cacheHealth.savings.fromCaching.toLocaleString()}`,
-      detail: 'Without prompt caching, standard input pricing would have applied to all cache reads. The system is working — optimization is about reducing breaks.',
-      action: 'Keep sessions alive to maximize hits. Avoid mid-session CLAUDE.md edits and MCP tool changes.',
+      title: `Cache saved ~$${cacheHealth.savings.fromCaching.toLocaleString()} in equivalent API costs`,
+      savings: 'Working as intended',
+      action: 'Prompt caching is saving you significantly. Keep sessions alive, avoid mid-session CLAUDE.md edits and MCP tool changes to maximize hits.',
     });
   }
 
-  // Cap at 5 most impactful recommendations
-  return recs.slice(0, 5);
+  return recs.slice(0, 8);
 }

package/src/readers/claude-md.js

@@ -28,10 +28,9 @@ export function readClaudeMdStack(claudeDir) {
     }
     if (currentSection.lines > 0) sections.push(currentSection);
 
-    // Add token estimates and sort by size
+    // Add token estimates, keep original file order (don't sort)
     globalSections = sections
-      .map(s => ({ ...s, tokens: Math.round(s.bytes / 4) }))
-      .sort((a, b) => b.bytes - a.bytes);
+      .map((s, idx) => ({ ...s, tokens: Math.round(s.bytes / 4), order: idx }));
 
     stack.push({
       level: 'global',

package/src/readers/jsonl-reader.js

@@ -36,20 +36,37 @@ function readProjectsDir(dir, entries) {
     for (const hash of projectHashes) {
       const projectDir = join(dir, hash);
 
-      // Read top-level JSONL files only (one per session).
-      // Subagent files in <session>/subagents/ are NOT read for cost —
-      // parent session JSONL already includes subagent token billing.
-      // Reading both would double-count (confirmed: $5.7K → $10.8K).
+      // Read top-level JSONL files (one per session)
       const jsonlFiles = readdirSync(projectDir).filter(f => f.endsWith('.jsonl'));
       for (const file of jsonlFiles) {
         readJsonlFile(join(projectDir, file), basename(file, '.jsonl'), hash, entries);
       }
+
+      // Read subagent JSONL files (for Haiku/Sonnet model attribution)
+      // Dedup by message ID prevents double-counting
+      const subdirs = readdirSync(projectDir).filter(f => {
+        try { return statSync(join(projectDir, f)).isDirectory(); } catch { return false; }
+      });
+      for (const subdir of subdirs) {
+        const subagentDir = join(projectDir, subdir, 'subagents');
+        if (existsSync(subagentDir)) {
+          try {
+            const subFiles = readdirSync(subagentDir).filter(f => f.endsWith('.jsonl'));
+            for (const file of subFiles) {
+              readJsonlFile(join(subagentDir, file), basename(file, '.jsonl'), hash, entries);
+            }
+          } catch { /* skip */ }
+        }
+      }
     }
   } catch {
     // Directory read failed
   }
 }
 
+// Track seen message IDs to deduplicate (JSONL files contain dupes from session resume)
+const seenMessageIds = new Set();
+
 function readJsonlFile(filePath, sessionId, projectHash, entries) {
   try {
     const raw = readFileSync(filePath, 'utf-8');
@@ -65,6 +82,13 @@ function readJsonlFile(filePath, sessionId, projectHash, entries) {
         const usage = record.message?.usage;
         if (!usage) continue;
 
+        // Deduplicate by message ID — JSONL files contain duplicates from session resume
+        const msgId = record.message?.id;
+        if (msgId) {
+          if (seenMessageIds.has(msgId)) continue;
+          seenMessageIds.add(msgId);
+        }
+
         entries.push({
           sessionId,
           projectHash,