cchubber 0.1.0

package/src/analyzers/inflection-detector.js

@@ -0,0 +1,67 @@
+/**
+ * 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."
+ */
+export function detectInflectionPoints(dailyFromJSONL) {
+  if (!dailyFromJSONL || dailyFromJSONL.length < 5) return null;
+
+  const sorted = [...dailyFromJSONL]
+    .filter(d => d.outputTokens > 0)
+    .sort((a, b) => a.date.localeCompare(b.date));
+
+  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 bestScore = 0;
+
+  for (let i = minWindow; i <= sorted.length - minWindow; i++) {
+    const before = sorted.slice(Math.max(0, i - 7), i);
+    const after = sorted.slice(i, Math.min(sorted.length, i + 7));
+
+    const beforeRatio = computeRatio(before);
+    const afterRatio = computeRatio(after);
+
+    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 (!bestSplit) 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.`;
+
+  return bestSplit;
+}
+
+function computeRatio(days) {
+  const totalOutput = days.reduce((s, d) => s + (d.outputTokens || 0), 0);
+  const totalCacheRead = days.reduce((s, d) => s + (d.cacheReadTokens || 0), 0);
+  return totalOutput > 0 ? Math.round(totalCacheRead / totalOutput) : 0;
+}
+
+function formatDate(dateStr) {
+  const d = new Date(dateStr + 'T00:00:00');
+  return d.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+}

package/src/analyzers/recommendations.js

@@ -0,0 +1,128 @@
+export function generateRecommendations(costAnalysis, cacheHealth, claudeMdStack, anomalies, inflection) {
+  const recs = [];
+
+  // 0. Inflection point — most important signal, goes first
+  if (inflection && inflection.direction === 'worsened' && inflection.multiplier >= 2) {
+    recs.push({
+      severity: 'critical',
+      title: `Efficiency dropped ${inflection.multiplier}x on ${inflection.date}`,
+      detail: inflection.summary,
+      action: 'This date likely correlates with a Claude Code update or cache regression. Check your CC version history. v2.1.89 had a known cache bug — v2.1.90 includes a fix.',
+    });
+  } 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: 'Something changed for the better on this date. Likely a version update or workflow change.',
+    });
+  }
+
+  // 1. CLAUDE.md size
+  if (claudeMdStack.totalTokensEstimate > 8000) {
+    recs.push({
+      severity: 'warning',
+      title: 'Large CLAUDE.md stack',
+      detail: `Your CLAUDE.md files total ~${claudeMdStack.totalTokensEstimate.toLocaleString()} tokens (${(claudeMdStack.totalBytes / 1024).toFixed(1)} KB). This is re-read on every message. At 200 messages/day, this costs ~$${claudeMdStack.costPerMessage.dailyCached200.toFixed(2)}/day cached, or $${claudeMdStack.costPerMessage.dailyUncached200.toFixed(2)}/day if cache breaks.`,
+      action: 'Review your CLAUDE.md for sections that could be moved to project-level files loaded on demand.',
+    });
+  }
+
+  // 2. Cache break frequency
+  if (cacheHealth.totalCacheBreaks > 10) {
+    const topReason = cacheHealth.reasonsRanked[0];
+    recs.push({
+      severity: cacheHealth.totalCacheBreaks > 50 ? 'critical' : 'warning',
+      title: `${cacheHealth.totalCacheBreaks} cache breaks detected`,
+      detail: `Each cache break forces a full context re-read at write prices (12.5x cache read cost). Top cause: "${topReason?.reason}" (${topReason?.count} times, ${topReason?.percentage}%).`,
+      action: topReason?.reason === 'Tool schemas changed'
+        ? 'Reduce MCP tool connections. Each tool add/remove invalidates the cache.'
+        : topReason?.reason === 'System prompt changed'
+        ? 'Avoid editing CLAUDE.md mid-session. Make changes between sessions.'
+        : topReason?.reason === 'TTL expiry'
+        ? 'Keep sessions active. Cache expires after 5 minutes of inactivity.'
+        : 'Review cache break logs in ~/.claude/tmp/cache-break-*.diff for details.',
+    });
+  }
+
+  // 3. High cache:output ratio
+  if (cacheHealth.efficiencyRatio > 2000) {
+    recs.push({
+      severity: 'critical',
+      title: `Cache efficiency ratio: ${cacheHealth.efficiencyRatio.toLocaleString()}:1`,
+      detail: `For every 1 token of output, ${cacheHealth.efficiencyRatio.toLocaleString()} tokens are read from cache. Healthy range is 300-800:1. This could indicate the known Claude Code cache bug (March 2026).`,
+      action: 'Check your Claude Code version. Versions around 2.1.85-2.1.90 have known cache regression bugs. Consider pinning to an earlier version.',
+    });
+  } else if (cacheHealth.efficiencyRatio > 1000) {
+    recs.push({
+      severity: 'warning',
+      title: `Elevated cache ratio: ${cacheHealth.efficiencyRatio.toLocaleString()}:1`,
+      detail: 'Above average but not critical. Could be large codebase exploration or heavy file reading.',
+      action: 'Use /compact more frequently in long sessions. Start fresh sessions for new tasks.',
+    });
+  }
+
+  // 4. Cost anomalies
+  if (anomalies.hasAnomalies) {
+    const spikes = anomalies.anomalies.filter(a => a.type === 'spike');
+    if (spikes.length > 0) {
+      const worst = spikes[0];
+      recs.push({
+        severity: worst.severity,
+        title: `${spikes.length} cost spike${spikes.length > 1 ? 's' : ''} detected`,
+        detail: `Worst: $${worst.cost.toFixed(2)} on ${worst.date} (${worst.zScore > 0 ? '+' : ''}${worst.deviation.toFixed(2)} from average of $${worst.avgCost.toFixed(2)}).${worst.cacheRatioAnomaly ? ' Cache ratio was also anomalous — likely cache bug impact.' : ''}`,
+        action: 'Compare session activity on spike days. Look for long sessions without /compact, or sessions where many MCP tools were connected.',
+      });
+    }
+  }
+
+  // 5. Cost trend
+  if (anomalies.trend === 'rising_fast') {
+    recs.push({
+      severity: 'critical',
+      title: 'Costs rising rapidly',
+      detail: 'Your recent 7-day average is significantly higher than your historical average.',
+      action: 'This may be related to the March 2026 Claude Code cache bug. Check Anthropic status for updates.',
+    });
+  }
+
+  // 6. Opus dominance
+  const modelCosts = costAnalysis.modelCosts || {};
+  const totalModelCost = Object.values(modelCosts).reduce((s, c) => s + c, 0);
+  const opusCost = Object.entries(modelCosts)
+    .filter(([name]) => name.includes('opus'))
+    .reduce((s, [, c]) => s + c, 0);
+  const opusPercentage = totalModelCost > 0 ? (opusCost / totalModelCost) * 100 : 0;
+
+  if (opusPercentage > 90) {
+    recs.push({
+      severity: 'info',
+      title: `${Math.round(opusPercentage)}% of costs from Opus`,
+      detail: 'Opus is the most expensive model. Subagents and simple tasks could use Sonnet or Haiku.',
+      action: 'Set model: "sonnet" or "haiku" on Task tool calls for search, documentation lookup, and log analysis.',
+    });
+  }
+
+  // 7. Session depth — long sessions without compact
+  const sessions = costAnalysis.sessions || {};
+  if (sessions.avgDurationMinutes > 60) {
+    recs.push({
+      severity: 'warning',
+      title: `Average session: ${Math.round(sessions.avgDurationMinutes)} minutes`,
+      detail: `Long sessions accumulate context that degrades both performance and cache efficiency. Sessions over 60 minutes often benefit from /compact.`,
+      action: 'Use /compact every 30-40 tool calls or when switching tasks. Start fresh sessions for new work.',
+    });
+  }
+
+  // 8. Caching savings acknowledgment
+  if (cacheHealth.savings.fromCaching > 100) {
+    recs.push({
+      severity: 'positive',
+      title: `Caching saved you ~$${cacheHealth.savings.fromCaching.toLocaleString()}`,
+      detail: 'Without prompt caching, your bill would be significantly higher. The cache system is working — the question is whether it breaks too often.',
+      action: 'No action needed. Keep sessions alive to maximize cache hits.',
+    });
+  }
+
+  return recs;
+}

package/src/cli/index.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+import { resolve, join } from 'path';
+import { existsSync, writeFileSync } from 'fs';
+import { homedir, platform } from 'os';
+import { exec } from 'child_process';
+
+import { readAllJSONL, aggregateDaily, aggregateByModel, aggregateByProject } from '../readers/jsonl-reader.js';
+import { readStatsCache } from '../readers/stats-cache.js';
+import { readSessionMeta } from '../readers/session-meta.js';
+import { readCacheBreaks } from '../readers/cache-breaks.js';
+import { readClaudeMdStack } from '../readers/claude-md.js';
+import { readOAuthUsage } from '../readers/oauth-usage.js';
+import { analyzeUsage, fetchPricing } from '../analyzers/cost-calculator.js';
+import { analyzeCacheHealth } from '../analyzers/cache-health.js';
+import { detectAnomalies } from '../analyzers/anomaly-detector.js';
+import { generateRecommendations } from '../analyzers/recommendations.js';
+import { detectInflectionPoints } from '../analyzers/inflection-detector.js';
+import { renderHTML } from '../renderers/html-report.js';
+import { renderTerminal } from '../renderers/terminal-summary.js';
+
+const args = process.argv.slice(2);
+const flags = {
+  help: args.includes('--help') || args.includes('-h'),
+  json: args.includes('--json'),
+  noOpen: args.includes('--no-open'),
+  output: (() => {
+    const idx = args.indexOf('--output') !== -1 ? args.indexOf('--output') : args.indexOf('-o');
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : null;
+  })(),
+  days: (() => {
+    const idx = args.indexOf('--days') !== -1 ? args.indexOf('--days') : args.indexOf('-d');
+    return idx !== -1 && args[idx + 1] ? parseInt(args[idx + 1], 10) : 30;
+  })(),
+};
+
+if (flags.help) {
+  console.log(`
+  ╔═══════════════════════════════════════════════╗
+  ║              CC Hubber v0.1.0                 ║
+  ║  What you spent. Why you spent it. Is that    ║
+  ║  normal.                                      ║
+  ╚═══════════════════════════════════════════════╝
+
+  Usage: cchubber [options]
+
+  Options:
+    --days, -d <n>     Analyze last N days (default: 30)
+    --output, -o <path> Output HTML report to custom path
+    --no-open          Don't auto-open the report in browser
+    --json             Output raw analysis as JSON
+    -h, --help         Show this help
+
+  Examples:
+    cchubber                    Scan & open HTML report
+    cchubber --days 7           Last 7 days only
+    cchubber -o report.html     Custom output path
+    cchubber --json             Machine-readable output
+
+  Shipped with Mover OS at speed.
+  https://moveros.dev
+`);
+  process.exit(0);
+}
+
+async function main() {
+  const claudeDir = getClaudeDir();
+
+  if (!existsSync(claudeDir)) {
+    console.error('\n  ✗ Claude Code data directory not found at: ' + claudeDir);
+    console.error('    Make sure Claude Code is installed and has been used at least once.\n');
+    process.exit(1);
+  }
+
+  console.log('\n  CC Hubber v0.1.0');
+  console.log('  ─────────────────────────────');
+  console.log('  Reading local Claude Code data...\n');
+
+  // Read all data sources
+  const jsonlEntries = readAllJSONL(claudeDir);
+  const statsCache = readStatsCache(claudeDir);
+  const sessionMeta = readSessionMeta(claudeDir);
+  const cacheBreaks = readCacheBreaks(claudeDir);
+  const claudeMdStack = readClaudeMdStack(claudeDir);
+  const oauthUsage = await readOAuthUsage(claudeDir);
+
+  if (jsonlEntries.length === 0 && !statsCache) {
+    console.error('  ✗ No usage data found. Use Claude Code first, then run CC Hubber.\n');
+    process.exit(1);
+  }
+
+  // Aggregate JSONL into daily + model + project views (primary data source)
+  const dailyFromJSONL = aggregateDaily(jsonlEntries);
+  const modelFromJSONL = aggregateByModel(jsonlEntries);
+  const projectBreakdown = aggregateByProject(jsonlEntries, claudeDir);
+
+  // Fetch dynamic pricing (LiteLLM) with hardcoded fallback
+  const pricing = await fetchPricing();
+  const pricingSource = pricing === null ? 'hardcoded' : 'LiteLLM';
+
+  console.log(`  ✓ ${jsonlEntries.length.toLocaleString()} conversation entries parsed`);
+  console.log(`  ✓ ${dailyFromJSONL.length} days of data found`);
+  console.log(`  ✓ Pricing: ${pricingSource}`);
+  console.log(`  ✓ ${sessionMeta.length} sessions found`);
+  console.log(`  ✓ ${cacheBreaks.length} cache break events found`);
+  console.log(`  ✓ CLAUDE.md stack: ${claudeMdStack.totalTokensEstimate.toLocaleString()} tokens (~${(claudeMdStack.totalBytes / 1024).toFixed(1)} KB)`);
+  if (oauthUsage) console.log('  ✓ Live rate limits loaded');
+  else console.log('  ○ Live rate limits skipped (no OAuth token)');
+
+  // Analyze — use ALL data for the HTML (client-side JS handles filtering)
+  // The --days flag sets the default view, but all data is embedded
+  console.log('\n  Analyzing...\n');
+  const allTimeDays = 99999; // Pass everything to the report
+  const costAnalysis = analyzeUsage(statsCache, sessionMeta, allTimeDays, dailyFromJSONL, modelFromJSONL);
+  const cacheHealth = analyzeCacheHealth(statsCache, cacheBreaks, allTimeDays, dailyFromJSONL);
+  const anomalies = detectAnomalies(costAnalysis);
+  const inflection = detectInflectionPoints(dailyFromJSONL);
+  const recommendations = generateRecommendations(costAnalysis, cacheHealth, claudeMdStack, anomalies, inflection);
+
+  if (inflection) {
+    console.log(`  ✓ Inflection point: ${inflection.summary}`);
+  }
+
+  console.log(`  ✓ ${projectBreakdown.length} projects detected`);
+
+  const report = {
+    generatedAt: new Date().toISOString(),
+    periodDays: flags.days, // Default view in HTML
+    costAnalysis,
+    cacheHealth,
+    anomalies,
+    inflection,
+    projectBreakdown,
+    claudeMdStack,
+    oauthUsage,
+    recommendations,
+  };
+
+  // Output
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  renderTerminal(report);
+
+  const outputPath = flags.output || join(process.cwd(), 'cchubber-report.html');
+  const html = renderHTML(report);
+  writeFileSync(outputPath, html, 'utf-8');
+  console.log(`\n  ✓ Report saved to: ${outputPath}`);
+
+  if (!flags.noOpen) {
+    openInBrowser(outputPath);
+    console.log('  ✓ Opened in browser\n');
+  }
+}
+
+function getClaudeDir() {
+  const home = homedir();
+  return join(home, '.claude');
+}
+
+function openInBrowser(filePath) {
+  const p = platform();
+  const cmd = p === 'win32' ? `start "" "${filePath}"`
+    : p === 'darwin' ? `open "${filePath}"`
+    : `xdg-open "${filePath}"`;
+  exec(cmd, (err) => { if (err) console.log('  ○ Could not auto-open browser. Open the file manually.'); });
+}
+
+main().catch((err) => {
+  console.error('\n  ✗ Error:', err.message);
+  process.exit(1);
+});

package/src/readers/cache-breaks.js

@@ -0,0 +1,81 @@
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+export function readCacheBreaks(claudeDir) {
+  const tmpDir = join(claudeDir, 'tmp');
+  if (!existsSync(tmpDir)) return [];
+
+  const breaks = [];
+
+  try {
+    const files = readdirSync(tmpDir).filter(f => f.startsWith('cache-break-') && f.endsWith('.diff'));
+
+    for (const file of files) {
+      try {
+        const raw = readFileSync(join(tmpDir, file), 'utf-8');
+        const parsed = parseCacheBreakDiff(raw, file);
+        if (parsed) breaks.push(parsed);
+      } catch {
+        // Skip unreadable files
+      }
+    }
+  } catch {
+    return [];
+  }
+
+  return breaks.sort((a, b) => (a.timestamp || '').localeCompare(b.timestamp || ''));
+}
+
+function parseCacheBreakDiff(content, filename) {
+  // Extract timestamp from filename: cache-break-<timestamp>.diff
+  const tsMatch = filename.match(/cache-break-(\d+)/);
+  const timestamp = tsMatch ? new Date(parseInt(tsMatch[1])).toISOString() : null;
+
+  // Parse the diff content for reasons
+  const reasons = [];
+  const lines = content.split('\n');
+
+  // Known cache break reason patterns from source code
+  const reasonPatterns = [
+    { pattern: /system.?prompt.?changed/i, reason: 'System prompt changed' },
+    { pattern: /tool.?schema.?changed/i, reason: 'Tool schemas changed' },
+    { pattern: /model.?changed/i, reason: 'Model changed' },
+    { pattern: /fast.?mode/i, reason: 'Fast mode toggled' },
+    { pattern: /cache.?strategy.?changed/i, reason: 'Cache strategy changed' },
+    { pattern: /cache.?control.?changed/i, reason: 'Cache control changed' },
+    { pattern: /betas?.?changed/i, reason: 'Betas header changed' },
+    { pattern: /auto.?mode/i, reason: 'Auto mode toggled' },
+    { pattern: /overage/i, reason: 'Overage state changed' },
+    { pattern: /microcompact/i, reason: 'Cached microcompact toggled' },
+    { pattern: /effort/i, reason: 'Effort value changed' },
+    { pattern: /extra.?body/i, reason: 'Extra body params changed' },
+    { pattern: /ttl/i, reason: 'TTL expiry' },
+    { pattern: /server.?side|evict/i, reason: 'Server-side eviction' },
+  ];
+
+  for (const line of lines) {
+    for (const { pattern, reason } of reasonPatterns) {
+      if (pattern.test(line) && !reasons.includes(reason)) {
+        reasons.push(reason);
+      }
+    }
+  }
+
+  // If no specific reason detected, mark as unknown
+  if (reasons.length === 0) {
+    reasons.push('Unknown / Server-side');
+  }
+
+  // Try to extract token counts from the diff
+  const prevCacheMatch = content.match(/prev(?:ious)?.*?cache.*?(\d[\d,]*)/i);
+  const newCacheMatch = content.match(/new.*?cache.*?(\d[\d,]*)/i);
+
+  return {
+    timestamp,
+    filename,
+    reasons,
+    rawContent: content.slice(0, 500), // Keep first 500 chars for debugging
+    prevCacheTokens: prevCacheMatch ? parseInt(prevCacheMatch[1].replace(/,/g, '')) : null,
+    newCacheTokens: newCacheMatch ? parseInt(newCacheMatch[1].replace(/,/g, '')) : null,
+  };
+}

package/src/readers/claude-md.js

@@ -0,0 +1,67 @@
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export function readClaudeMdStack(claudeDir) {
+  const home = homedir();
+  const stack = [];
+
+  // Global CLAUDE.md
+  const globalPath = join(home, '.claude', 'CLAUDE.md');
+  if (existsSync(globalPath)) {
+    const stat = statSync(globalPath);
+    stack.push({
+      level: 'global',
+      path: globalPath,
+      bytes: stat.size,
+      tokensEstimate: Math.round(stat.size / 4),
+    });
+  }
+
+  // Try to find project-level CLAUDE.md by walking up from cwd
+  let dir = process.cwd();
+  const checked = new Set();
+  while (dir && !checked.has(dir)) {
+    checked.add(dir);
+    const projectMd = join(dir, 'CLAUDE.md');
+    if (existsSync(projectMd) && projectMd !== globalPath) {
+      const stat = statSync(projectMd);
+      stack.push({
+        level: 'project',
+        path: projectMd,
+        bytes: stat.size,
+        tokensEstimate: Math.round(stat.size / 4),
+      });
+    }
+    const parent = join(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Check for .claude/settings.json to understand hook/skill overhead
+  const settingsPath = join(home, '.claude', 'settings.json');
+  let settingsSize = 0;
+  if (existsSync(settingsPath)) {
+    settingsSize = statSync(settingsPath).size;
+  }
+
+  const totalBytes = stack.reduce((sum, f) => sum + f.bytes, 0);
+  const totalTokensEstimate = stack.reduce((sum, f) => sum + f.tokensEstimate, 0);
+
+  // Estimate per-message cost at different cache rates (Opus 4.6)
+  const cachedCostPerMsg = totalTokensEstimate * 0.0000005;   // $0.50/M cache read
+  const uncachedCostPerMsg = totalTokensEstimate * 0.000005;  // $5.00/M standard input
+
+  return {
+    files: stack,
+    totalBytes,
+    totalTokensEstimate,
+    settingsBytes: settingsSize,
+    costPerMessage: {
+      cached: cachedCostPerMsg,
+      uncached: uncachedCostPerMsg,
+      dailyCached200: cachedCostPerMsg * 200,
+      dailyUncached200: uncachedCostPerMsg * 200,
+    },
+  };
+}