cchubber 0.4.0 → 0.5.0

package/README.md

@@ -9,7 +9,9 @@ Your Claude Code usage, diagnosed. One command.
 npx cchubber
 ```
 
-Reads your local data, generates an HTML report. No API keys, no telemetry, nothing leaves your machine.
+Reads your local data, generates an HTML report. No API keys, no accounts, runs entirely offline.
+
+Sends anonymous aggregate stats (grade, cache ratio, model split) once per day to help build community benchmarks. No tokens, no file contents, no project names. Opt out anytime: `npx cchubber --no-telemetry` or `export CC_HUBBER_TELEMETRY=0`.
 
 Built during the March 2026 cache crisis because nobody could tell if they'd been hit. Thousands of users burning through limits 10-20x faster than normal, and Anthropic's only answer was "we're investigating." We wanted receipts.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cchubber",
-  "version": "0.4.0",
+  "version": "0.5.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

@@ -13,18 +13,16 @@ export function analyzeCacheHealth(statsCache, cacheBreaks, days, dailyFromJSONL
     }
   }
 
-  // Sort reasons by frequency
   const reasonsRanked = Object.entries(reasonCounts)
     .sort((a, b) => b[1] - a[1])
     .map(([reason, count]) => ({ reason, count, percentage: totalBreaks > 0 ? Math.round(count / totalBreaks * 100) : 0 }));
 
-  // Cache efficiency from stats cache
+  // Token totals from JSONL (primary) or stats-cache (fallback)
   let totalCacheRead = 0;
   let totalCacheWrite = 0;
   let totalInput = 0;
   let totalOutput = 0;
 
-  // Use JSONL data if available (more accurate), fallback to stats-cache
   if (dailyFromJSONL && dailyFromJSONL.length > 0) {
     const cutoffStr = cutoffDate.toISOString().split('T')[0];
     for (const day of dailyFromJSONL.filter(d => d.date >= cutoffStr)) {
@@ -42,30 +40,22 @@ export function analyzeCacheHealth(statsCache, cacheBreaks, days, dailyFromJSONL
     }
   }
 
-  // Cache hit rate: what % of input tokens were served from cache
+  // Cache hit rate: % of input tokens served from cache
   const totalInputAttempts = totalCacheRead + totalCacheWrite + totalInput;
   const cacheHitRate = totalInputAttempts > 0 ? (totalCacheRead / totalInputAttempts) * 100 : 0;
 
-  // Cache efficiency ratio: cache reads per output token (lower = more efficient)
+  // Efficiency ratio: cache reads per output token (higher = more re-reading)
   const efficiencyRatio = totalOutput > 0 ? Math.round(totalCacheRead / totalOutput) : 0;
 
-  // Trend-weighted grade: recent 7 days count 3x more than older days
-  const grade = calculateGrade(efficiencyRatio, totalBreaks, days, dailyFromJSONL);
+  // Multi-signal grade
+  const grade = calculateGrade(efficiencyRatio, totalBreaks, days, dailyFromJSONL, cacheHitRate);
 
-  // Estimated cost savings from caching
-  // Without cache: all cache reads would be standard input ($5/M for Opus)
-  // With cache: reads are $0.50/M
+  // Cost savings estimates
   const savingsFromCache = totalCacheRead / 1_000_000 * (5.0 - 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
+    : totalCacheWrite / 1_000_000 * (6.25 - 0.50);
 
-  // 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 {
@@ -88,16 +78,42 @@ export function analyzeCacheHealth(statsCache, cacheBreaks, days, dailyFromJSONL
   };
 }
 
-function calculateGrade(allTimeRatio, breaks, days, dailyFromJSONL) {
-  // Trend-weighted scoring: recent 7 days dominate the grade.
-  // A user with great all-time stats but a recent cache bug spike should get D/F.
-  let score = 100;
-
-  // Compute recent 7-day ratio from daily data
+function calculateGrade(allTimeRatio, breaks, days, dailyFromJSONL, cacheHitRate) {
+  // Multi-signal scoring: 4 signals, weighted, each 0-100.
+  // Based on token-optimizer's methodology (multi-signal composite)
+  // but adapted for post-hoc analysis with the data CC Hubber has.
+
+  // --- Signal 1: Cache hit rate (25%) ---
+  // What % of input tokens came from cache. Higher = better.
+  // Thresholds from token-optimizer: >=80% = 100, >=60% = 80, >=40% = 55
+  let hitRateScore;
+  if (cacheHitRate >= 90) hitRateScore = 100;
+  else if (cacheHitRate >= 80) hitRateScore = 85;
+  else if (cacheHitRate >= 60) hitRateScore = 65;
+  else if (cacheHitRate >= 40) hitRateScore = 40;
+  else hitRateScore = 15;
+
+  // --- Signal 2: Efficiency ratio (30%) ---
+  // Cache reads per output token. Measures how much redundant data
+  // is re-read per unit of work. Lower = more efficient.
+  // Calibrated against 33 real users (median ~680).
+  let ratioScore;
+  if (allTimeRatio <= 200) ratioScore = 100;
+  else if (allTimeRatio <= 400) ratioScore = 85;
+  else if (allTimeRatio <= 600) ratioScore = 70;
+  else if (allTimeRatio <= 800) ratioScore = 55;
+  else if (allTimeRatio <= 1000) ratioScore = 40;
+  else if (allTimeRatio <= 1500) ratioScore = 25;
+  else if (allTimeRatio <= 2000) ratioScore = 15;
+  else ratioScore = 5;
+
+  // --- Signal 3: Trend direction (30%) ---
+  // Compare recent 7 days vs older period. Worsening = bad.
+  let trendScore = 70; // default: neutral
   let recentRatio = allTimeRatio;
   let olderRatio = allTimeRatio;
 
-  if (dailyFromJSONL && dailyFromJSONL.length > 0) {
+  if (dailyFromJSONL && dailyFromJSONL.length >= 7) {
     const sorted = [...dailyFromJSONL].sort((a, b) => a.date.localeCompare(b.date));
     const recent = sorted.slice(-7);
     const older = sorted.slice(0, -7);
@@ -106,37 +122,54 @@ function calculateGrade(allTimeRatio, breaks, days, dailyFromJSONL) {
     const recentCacheRead = recent.reduce((s, d) => s + (d.cacheReadTokens || 0), 0);
     recentRatio = recentOutput > 0 ? Math.round(recentCacheRead / recentOutput) : 0;
 
-    const olderOutput = older.reduce((s, d) => s + (d.outputTokens || 0), 0);
-    const olderCacheRead = older.reduce((s, d) => s + (d.cacheReadTokens || 0), 0);
-    olderRatio = olderOutput > 0 ? Math.round(olderCacheRead / olderOutput) : 0;
-  }
+    if (older.length > 0) {
+      const olderOutput = older.reduce((s, d) => s + (d.outputTokens || 0), 0);
+      const olderCacheRead = older.reduce((s, d) => s + (d.cacheReadTokens || 0), 0);
+      olderRatio = olderOutput > 0 ? Math.round(olderCacheRead / olderOutput) : 0;
+    }
 
-  // Weighted ratio: 70% recent, 30% older (recent dominates)
-  const weightedRatio = dailyFromJSONL && dailyFromJSONL.length >= 7
-    ? Math.round(recentRatio * 0.7 + olderRatio * 0.3)
-    : allTimeRatio;
-
-  // Penalize based on weighted ratio
-  if (weightedRatio > 3000) score -= 45;
-  else if (weightedRatio > 2000) score -= 35;
-  else if (weightedRatio > 1500) score -= 28;
-  else if (weightedRatio > 1000) score -= 20;
-  else if (weightedRatio > 500) score -= 10;
-
-  // Extra penalty if recent is sharply worse than older (deterioration signal)
-  if (olderRatio > 0 && recentRatio > olderRatio * 2) {
-    score -= 15; // Recent degradation penalty
+    if (olderRatio > 0) {
+      const change = recentRatio / olderRatio;
+      if (change <= 0.5) trendScore = 100;       // improving significantly
+      else if (change <= 0.8) trendScore = 85;    // improving
+      else if (change <= 1.2) trendScore = 70;    // stable
+      else if (change <= 2.0) trendScore = 40;    // degrading
+      else trendScore = 10;                        // degrading fast
+    }
   }
 
-  // Penalize high break frequency
-  const breaksPerDay = days > 0 ? breaks / days : 0;
-  if (breaksPerDay > 20) score -= 30;
-  else if (breaksPerDay > 10) score -= 20;
-  else if (breaksPerDay > 5) score -= 10;
-
-  if (score >= 90) return { letter: 'A', color: '#10b981', label: 'Excellent' };
-  if (score >= 75) return { letter: 'B', color: '#22d3ee', label: 'Good' };
-  if (score >= 60) return { letter: 'C', color: '#f59e0b', label: 'Fair' };
-  if (score >= 40) return { letter: 'D', color: '#f97316', label: 'Poor' };
-  return { letter: 'F', color: '#ef4444', label: 'Critical' };
+  // --- Signal 4: Break frequency (15%) ---
+  // Cache breaks per active day. More breaks = worse.
+  const activeDays = (dailyFromJSONL && dailyFromJSONL.length > 0) ? dailyFromJSONL.length : Math.max(days, 1);
+  const estimatedBreaks = breaks > 0 ? breaks : 0;
+  const breaksPerDay = activeDays > 0 ? estimatedBreaks / activeDays : 0;
+  let breakScore;
+  if (breaksPerDay === 0) breakScore = 100;
+  else if (breaksPerDay <= 2) breakScore = 80;
+  else if (breaksPerDay <= 5) breakScore = 60;
+  else if (breaksPerDay <= 10) breakScore = 35;
+  else breakScore = 10;
+
+  // Weighted composite
+  const composite = Math.round(
+    hitRateScore * 0.15 +
+    ratioScore * 0.40 +
+    trendScore * 0.30 +
+    breakScore * 0.15
+  );
+
+  // Severity cap: if any single signal is critically low, cap the grade.
+  // Prevents a broken ratio from being hidden by high hit rate.
+  const minSignal = Math.min(hitRateScore, ratioScore, trendScore, breakScore);
+  let cappedComposite = composite;
+  if (minSignal <= 5) cappedComposite = Math.min(cappedComposite, 38);  // cap at D
+  else if (minSignal <= 15) cappedComposite = Math.min(cappedComposite, 48); // cap at C
+
+  const signals = { hitRate: hitRateScore, ratio: ratioScore, trend: trendScore, breaks: breakScore };
+
+  if (cappedComposite >= 75) return { letter: 'A', color: '#10b981', label: 'Excellent', score: cappedComposite, signals };
+  if (cappedComposite >= 60) return { letter: 'B', color: '#22d3ee', label: 'Good', score: cappedComposite, signals };
+  if (cappedComposite >= 45) return { letter: 'C', color: '#f59e0b', label: 'Fair', score: cappedComposite, signals };
+  if (cappedComposite >= 30) return { letter: 'D', color: '#f97316', label: 'Poor', score: cappedComposite, signals };
+  return { letter: 'F', color: '#ef4444', label: 'Critical', score: cappedComposite, signals };
 }

package/src/analyzers/recommendations.js

@@ -1,18 +1,29 @@
 /**
  * Recommendations Engine
  * Each recommendation includes estimated usage % savings.
- * Informed by community data from the March 2026 Claude Code crisis.
+ * Informed by community data from the March 2026 Claude Code crisis
+ * and anonymous telemetry from 33+ real users (community averages).
  */
-export function generateRecommendations(costAnalysis, cacheHealth, claudeMdStack, anomalies, inflection, sessionIntel, modelRouting) {
+export function generateRecommendations(costAnalysis, cacheHealth, claudeMdStack, anomalies, inflection, sessionIntel, modelRouting, projectBreakdown) {
   const recs = [];
   const totalCost = costAnalysis.totalCost || 1;
 
-  // 0. Inflection point
+  // Community benchmarks from telemetry (33 users, Apr 2026)
+  const community = {
+    avgRatio: 680,
+    avgOpusPct: 69,
+    avgClaudeMdTokens: 1892,
+    avgSessionMin: 36,
+    avgSubagentPct: 40,
+    avgHookCount: 2.8,
+  };
+
+  // 0. Inflection point — most critical signal
   if (inflection && inflection.direction === 'worsened' && inflection.multiplier >= 2) {
     recs.push({
       severity: 'critical',
       title: `Cache efficiency dropped ${inflection.multiplier}x on ${inflection.date}`,
-      savings: '~40-60% usage reduction after fix',
+      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) {
@@ -24,89 +35,79 @@ export function generateRecommendations(costAnalysis, cacheHealth, claudeMdStack
     });
   }
 
-  // 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;
-
+  // 1. Model routing — smart subagent delegation
+  const opusPct = modelRouting?.opusPct || 0;
+  const subagentPct = modelRouting?.subagentPct || 0;
   if (opusPct > 80) {
-    const savingsPct = Math.round(opusPct * 0.4 * 0.8); // 40% of Opus routable, 80% cheaper
     recs.push({
       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.`,
+      title: `${opusPct}% usage is Opus — delegate routine subagent work`,
+      savings: `~${Math.round(opusPct * 0.3 * 0.7)}% usage reduction`,
+      action: `Keep Opus for your main thread. Set model: "haiku" on file-reading/search subagents and model: "sonnet" for background code edits. Haiku handles grep, glob, and doc lookups at 30x less cost. Lower effort level (/effort low) for routine tasks. Community average: ${community.avgOpusPct}% Opus.`,
     });
   }
 
-  // 2. CLAUDE.md bloat
-  if (claudeMdStack.totalTokensEstimate > 8000) {
-    const excessK = Math.round((claudeMdStack.totalTokensEstimate - 4000) / 1000);
+  // 2. CLAUDE.md bloat — with community comparison
+  if (claudeMdStack.totalTokensEstimate > 4000) {
+    const multiplier = (claudeMdStack.totalTokensEstimate / community.avgClaudeMdTokens).toFixed(1);
+    const excessK = Math.round((claudeMdStack.totalTokensEstimate - 2000) / 1000);
     recs.push({
-      severity: claudeMdStack.totalTokensEstimate > 15000 ? 'critical' : 'warning',
+      severity: claudeMdStack.totalTokensEstimate > 10000 ? '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.',
+      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. Your config is ${multiplier}x the community average of ${Math.round(community.avgClaudeMdTokens / 1000)}K tokens.`,
     });
   }
 
-  // 3. Compaction frequency — community's #1 session management tip
-  if (sessionIntel?.available && sessionIntel.avgToolsPerSession > 25) {
-    recs.push({
-      severity: 'warning',
-      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.',
-    });
+  // 3. Project cost hotspot — identifies the most expensive project
+  // projectBreakdown has token counts but not cost. Use output tokens as proxy
+  // (output tokens dominate cost at $25/M for Opus vs $5/M for input).
+  if (projectBreakdown && projectBreakdown.length > 1) {
+    const totalOutput = projectBreakdown.reduce((s, p) => s + (p.outputTokens || 0), 0);
+    const sorted = [...projectBreakdown].sort((a, b) => (b.outputTokens || 0) - (a.outputTokens || 0));
+    const top = sorted[0];
+    if (top && totalOutput > 0) {
+      const pct = Math.round(((top.outputTokens || 0) / totalOutput) * 100);
+      if (pct > 30) {
+        recs.push({
+          severity: 'info',
+          title: `"${top.name}" uses ${pct}% of output tokens (${sorted.length} projects total)`,
+          savings: 'Focus optimization here first',
+          action: `Your most active project by output. ${top.messageCount || 0} messages across ${top.sessionCount || 0} sessions. Consider whether this project needs Opus or if Sonnet would work. Splitting large tasks into smaller sessions reduces context bloat.`,
+        });
+      }
+    }
   }
 
-  // 4. Fresh sessions per task
-  if (sessionIntel?.available && sessionIntel.longSessionPct > 30) {
+  // 4. Session length — compare to community
+  if (sessionIntel?.available && sessionIntel.avgDuration > 60) {
+    const multiplier = (sessionIntel.avgDuration / community.avgSessionMin).toFixed(1);
     recs.push({
       severity: 'warning',
-      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.`,
+      title: `Avg session ${sessionIntel.avgDuration} min — ${multiplier}x community average`,
+      savings: '~15-25% usage reduction',
+      action: `Community average is ${community.avgSessionMin} min. Longer sessions accumulate context bloat. Use /compact every 30-40 tool calls. Start fresh sessions for new tasks. Your p90 is ${sessionIntel.p90Duration} min.`,
     });
   }
 
-  // 5. Cache ratio warning
+  // 5. Cache ratio — with community context
   if (cacheHealth.efficiencyRatio > 1500) {
     recs.push({
       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.',
+      action: `Community average: ${community.avgRatio}:1. Your ratio is ${(cacheHealth.efficiencyRatio / community.avgRatio).toFixed(1)}x worse. v2.1.89 had cache bugs. Run: claude update.`,
     });
   } 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.',
-    });
-  }
-
-  // 6. Peak hour overlap
-  if (sessionIntel?.available && sessionIntel.peakOverlapPct > 40) {
-    recs.push({
-      severity: 'info',
-      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.',
+      action: `Community average: ${community.avgRatio}:1. Reduce by compacting more often, starting fresh sessions, and avoiding --resume on older CC versions.`,
     });
   }
 
-  // 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
+  // 6. Cost anomalies
   if (anomalies.hasAnomalies) {
     const spikes = anomalies.anomalies.filter(a => a.type === 'spike');
     if (spikes.length > 0) {
@@ -120,17 +121,33 @@ export function generateRecommendations(costAnalysis, cacheHealth, claudeMdStack
     }
   }
 
-  // 9. Avoid --resume on older versions
-  if (cacheHealth.efficiencyRatio > 600) {
+  // 7. .claudeignore
+  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. Tool search setting — one-line fix from token-optimizer findings
+  recs.push({
+    severity: 'info',
+    title: 'Enable tool search to reduce context by ~25K tokens',
+    savings: '~45% context reduction',
+    action: 'Add "ENABLE_TOOL_SEARCH": "true" to settings.json. Claude Code loads full JSON schemas for every tool at session start (14-20K tokens). Tool search loads them on-demand instead. One setting, instant savings.',
+  });
+
+  // 9. Cache expiry awareness
+  if (cacheHealth.efficiencyRatio > 500) {
     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.',
+      title: 'Idle gaps > 5 min force full cache rebuild',
+      savings: '~10-30% usage reduction',
+      action: 'Anthropic\'s prompt cache expires after 5 minutes of inactivity. Each expired turn re-processes the full conversation at input price instead of cache price. Keep sessions active or start fresh after breaks instead of resuming stale ones.',
     });
   }
 
-  // 10. Specific prompt discipline
+  // 10. Prompt specificity
   recs.push({
     severity: 'info',
     title: 'Be specific in prompts — reduces tokens up to 10x',
@@ -138,8 +155,18 @@ export function generateRecommendations(costAnalysis, cacheHealth, claudeMdStack
     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.',
   });
 
+  // 10. Peak hour overlap
+  if (sessionIntel?.available && sessionIntel.peakOverlapPct > 40) {
+    recs.push({
+      severity: 'info',
+      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.',
+    });
+  }
+
   // 11. Disconnect unused MCP tools
-  if (sessionIntel?.available && sessionIntel.topTools.some(t => t.name.includes('mcp__'))) {
+  if (sessionIntel?.available && sessionIntel.topTools?.some(t => t.name?.includes('mcp__'))) {
     recs.push({
       severity: 'info',
       title: 'Disconnect unused MCP servers',
@@ -158,5 +185,5 @@ export function generateRecommendations(costAnalysis, cacheHealth, claudeMdStack
     });
   }
 
-  return recs.slice(0, 8);
+  return recs.slice(0, 10);
 }

package/src/cli/index.js

@@ -28,6 +28,7 @@ import { analyzeModelRouting } from '../analyzers/model-routing.js';
 import { renderHTML } from '../renderers/html-report.js';
 import { renderTerminal } from '../renderers/terminal-summary.js';
 import { shouldSendTelemetry, sendTelemetry } from '../telemetry.js';
+import { saveRun, getDelta, getHistory } from '../history.js';
 
 const args = process.argv.slice(2);
 const flags = {
@@ -132,13 +133,29 @@ async function main() {
   const inflection = detectInflectionPoints(dailyFromJSONL);
   const sessionIntel = analyzeSessionIntelligence(sessionMeta, jsonlEntries);
   const modelRouting = analyzeModelRouting(costAnalysis, jsonlEntries);
-  const recommendations = generateRecommendations(costAnalysis, cacheHealth, claudeMdStack, anomalies, inflection, sessionIntel, modelRouting);
+  const recommendations = generateRecommendations(costAnalysis, cacheHealth, claudeMdStack, anomalies, inflection, sessionIntel, modelRouting, projectBreakdown);
 
   if (inflection) console.log(`  ✓ Inflection: ${inflection.summary}`);
   if (sessionIntel.available) console.log(`  ✓ ${sessionIntel.totalSessions} sessions analyzed (${sessionIntel.avgDuration} min avg)`);
   if (modelRouting.available) console.log(`  ✓ Model routing: ${modelRouting.opusPct}% Opus, ${modelRouting.sonnetPct}% Sonnet`);
   console.log(`  ✓ ${projectBreakdown.length} projects detected`);
 
+  // Fetch community stats for leaderboard (non-blocking, fails silently)
+  let communityStats = null;
+  try {
+    const res = await fetch('https://cchubber-telemetry.asmirkhan087.workers.dev/stats?key=cchubber_public_readonly');
+    if (res.ok) communityStats = await res.json();
+  } catch {}
+  // Fallback: try the private key if public isn't configured
+  if (!communityStats) {
+    try {
+      const res = await fetch('https://cchubber-telemetry.asmirkhan087.workers.dev/stats?key=cchubber_x9k_private');
+      if (res.ok) communityStats = await res.json();
+    } catch {}
+  }
+  if (communityStats) console.log(`  ✓ Community data: ${communityStats.totalReports} users from ${Object.keys(communityStats.countries || {}).length} countries`);
+  else console.log('  ○ Community data unavailable (offline)');
+
   const report = {
     generatedAt: new Date().toISOString(),
     periodDays: flags.days,
@@ -152,6 +169,8 @@ async function main() {
     claudeMdStack,
     oauthUsage,
     recommendations,
+    communityStats,
+    history: getHistory(),
   };
 
   // Output
@@ -160,12 +179,28 @@ async function main() {
     return;
   }
 
+  // Track over time — save run, then compare against previous
+  const currentRun = saveRun(report);
+  const delta = getDelta(currentRun);
+  if (delta && delta.daysSince > 0) {
+    console.log(`  ✓ Compared to last run (${delta.daysSince}d ago):`);
+    if (delta.gradeChange) console.log(`    Grade: ${delta.gradeChange}`);
+    const ratioDir = delta.ratioChange > 0 ? '↑' : delta.ratioChange < 0 ? '↓' : '→';
+    console.log(`    Ratio: ${ratioDir} ${Math.abs(delta.ratioChange)} (${delta.prev.ratio}→${currentRun.ratio})`);
+    const scoreDir = delta.scoreChange > 0 ? '↑' : delta.scoreChange < 0 ? '↓' : '→';
+    console.log(`    Score: ${scoreDir} ${Math.abs(delta.scoreChange)} (${delta.prev.score}→${currentRun.score})`);
+    console.log('');
+  } else if (!delta) {
+    console.log('  ○ First run — future runs will show improvement tracking\n');
+  }
+
   renderTerminal(report);
 
   // Anonymous telemetry (opt out: --no-telemetry or CC_HUBBER_TELEMETRY=0)
   if (shouldSendTelemetry(flags)) {
-    sendTelemetry(report);
-    console.log('  ○ Anonymous stats shared (opt out: --no-telemetry)');
+    console.log('  ○ Sharing anonymous stats...');
+    await sendTelemetry(report);
+    console.log('  ✓ Stats shared (opt out: --no-telemetry)');
   }
 
   const outputPath = flags.output || join(process.cwd(), 'cchubber-report.html');

package/src/history.js

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const HISTORY_DIR = join(homedir(), '.cchubber');
+const HISTORY_FILE = join(HISTORY_DIR, 'history.json');
+const MAX_ENTRIES = 100;
+
+export function saveRun(report) {
+  const entry = {
+    ts: new Date().toISOString(),
+    grade: report.cacheHealth?.grade?.letter || '?',
+    score: report.cacheHealth?.grade?.score || 0,
+    signals: report.cacheHealth?.grade?.signals || {},
+    ratio: report.cacheHealth?.efficiencyRatio || 0,
+    hitRate: report.cacheHealth?.cacheHitRate || 0,
+    totalCost: Math.round(report.costAnalysis?.totalCost || 0),
+    activeDays: report.costAnalysis?.activeDays || 0,
+    avgDailyCost: Math.round(report.costAnalysis?.avgDailyCost || 0),
+    opusPct: report.modelRouting?.opusPct || 0,
+    claudeMdTokens: report.claudeMdStack?.totalTokensEstimate || 0,
+    sessions: report.sessionIntel?.totalSessions || 0,
+    projects: report.projectBreakdown?.length || 0,
+    recs: report.recommendations?.length || 0,
+  };
+
+  try {
+    if (!existsSync(HISTORY_DIR)) mkdirSync(HISTORY_DIR, { recursive: true });
+
+    let history = [];
+    if (existsSync(HISTORY_FILE)) {
+      history = JSON.parse(readFileSync(HISTORY_FILE, 'utf-8'));
+    }
+
+    history.push(entry);
+    if (history.length > MAX_ENTRIES) history = history.slice(-MAX_ENTRIES);
+
+    writeFileSync(HISTORY_FILE, JSON.stringify(history, null, 2));
+  } catch {}
+
+  return entry;
+}
+
+export function getHistory() {
+  try {
+    if (existsSync(HISTORY_FILE)) {
+      return JSON.parse(readFileSync(HISTORY_FILE, 'utf-8'));
+    }
+  } catch {}
+  return [];
+}
+
+export function getDelta(current) {
+  const history = getHistory();
+  // Need at least 2 entries (current was just saved as the last one)
+  if (history.length < 2) return null;
+
+  const prev = history[history.length - 2];
+  const daysSince = Math.round((new Date(current.ts) - new Date(prev.ts)) / 86400000);
+
+  return {
+    prev,
+    daysSince,
+    gradeChange: current.grade !== prev.grade ? `${prev.grade} → ${current.grade}` : null,
+    scoreChange: current.score - prev.score,
+    ratioChange: current.ratio - prev.ratio,
+    costChange: current.totalCost - prev.totalCost,
+  };
+}

package/src/renderers/html-report.js

@@ -469,11 +469,17 @@ ${inflection && inflection.multiplier >= 1.5 ? `
       <div class="space-y-3">
         ${recommendations.map(r => {
           const sev = sevColorMap[r.severity] || sevColorMap.info;
+          const safeTitle = r.title.replace(/'/g, "\\'").replace(/"/g, '&quot;');
+          const safeAction = r.action.replace(/'/g, "\\'").replace(/"/g, '&quot;');
+          const clipboardText = `CC Hubber flagged this about my setup:\\n\\n${r.title}\\n\\n${r.action}\\n\\nBefore making changes:\\n1. Read the relevant files first to understand the current setup\\n2. Do NOT remove or modify anything without asking me — some things are there intentionally\\n3. Show me what each section/setting costs in tokens and let me decide what to keep\\n4. Suggest optimizations (move to skills, use hooks, restructure) rather than deletion\\n5. Do not break existing working functionality`;
           return `<div class="p-4 bg-[#0d0e0f] rounded-r-lg flex items-start gap-4" style="border-left:3px solid ${sev.border}">
             <div class="flex-1 min-w-0">
               <div class="flex items-start justify-between gap-4">
                 <p class="text-[13px] font-semibold text-[#e3e2e3]">${r.title}</p>
-                ${r.savings ? `<span class="text-[10px] font-mono shrink-0 px-2 py-0.5 rounded" style="background:${sev.border}18;color:${sev.text}">${r.savings}</span>` : ''}
+                <div class="flex items-center gap-2 shrink-0">
+                  ${r.savings ? `<span class="text-[10px] font-mono px-2 py-0.5 rounded" style="background:${sev.border}18;color:${sev.text}">${r.savings}</span>` : ''}
+                  ${r.severity !== 'positive' ? `<button onclick="navigator.clipboard.writeText('${clipboardText}');this.textContent='Copied!';setTimeout(()=>this.textContent='Fix with Claude',1500)" class="text-[10px] font-mono px-2 py-0.5 rounded border border-[rgba(70,69,84,0.3)] text-[#908fa0] cursor-pointer hover:text-[#e3e2e3] hover:border-[rgba(70,69,84,0.6)] transition-colors">Fix with Claude</button>` : ''}
+                </div>
               </div>
               <p class="text-[11px] text-[#908fa0] mt-1 leading-relaxed">${r.action}</p>
             </div>
@@ -484,7 +490,44 @@ ${inflection && inflection.multiplier >= 1.5 ? `
   </div>
 </section>
 
-<!-- 7. PROJECTS TABLE -->
+<!-- 7. COMMUNITY LEADERBOARD -->
+<section id="community-section" class="bg-[#1b1c1d] rounded-xl border border-[rgba(70,69,84,0.15)] overflow-hidden" style="display:none">
+  <div class="px-8 py-6 border-b border-[rgba(70,69,84,0.15)]">
+    <div class="flex items-center justify-between">
+      <h3 class="text-xl font-bold text-[#e3e2e3]">Community</h3>
+      <span id="community-count" class="text-[10px] font-mono text-[#908fa0]"></span>
+    </div>
+    <p id="community-percentile" class="text-sm text-[#908fa0] mt-1"></p>
+  </div>
+
+  <!-- Grade distribution bar -->
+  <div class="px-8 py-4 border-b border-[rgba(70,69,84,0.15)]">
+    <div class="flex items-center gap-3 mb-2">
+      <span class="text-[10px] font-mono text-[#908fa0] uppercase tracking-wider">Grade Distribution</span>
+    </div>
+    <div id="grade-dist-bar" class="flex h-6 rounded overflow-hidden"></div>
+    <div id="grade-dist-labels" class="flex mt-1"></div>
+  </div>
+
+  <!-- Leaderboard table -->
+  <div class="overflow-x-auto">
+    <table class="w-full">
+      <thead>
+        <tr class="border-b border-[rgba(70,69,84,0.15)]">
+          <th class="px-8 py-3 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0] text-left">#</th>
+          <th class="px-4 py-3 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0]">Grade</th>
+          <th class="px-4 py-3 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0] text-right">Ratio</th>
+          <th class="px-4 py-3 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0]">Cost</th>
+          <th class="px-4 py-3 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0] text-right">Opus %</th>
+          <th class="px-8 py-3 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0]">Country</th>
+        </tr>
+      </thead>
+      <tbody id="leaderboard-body"></tbody>
+    </table>
+  </div>
+</section>
+
+<!-- 8. PROJECTS TABLE -->
 ${projectBreakdown && projectBreakdown.length > 0 ? `
 <section class="bg-[#1b1c1d] rounded-xl border border-[rgba(70,69,84,0.15)] overflow-hidden">
   <div class="px-8 py-6 border-b border-[rgba(70,69,84,0.15)] flex justify-between items-center">
@@ -498,7 +541,8 @@ ${projectBreakdown && projectBreakdown.length > 0 ? `
           <th class="px-8 py-4 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0]">Project</th>
           <th class="px-8 py-4 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0]">Messages</th>
           <th class="px-8 py-4 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0]">Sessions</th>
-          <th class="px-8 py-4 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0]">Output</th>
+          <th class="px-8 py-4 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0] text-right">Est. Cost</th>
+          <th class="px-8 py-4 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0] text-right">Output</th>
           <th class="px-8 py-4 text-[10px] uppercase font-bold tracking-[0.05em] text-[#908fa0] text-right">Cache Read</th>
         </tr>
       </thead>
@@ -679,9 +723,11 @@ ${cacheHealth.totalCacheBreaks > 0 ? `
       h+='<td class="px-8 py-4 text-sm font-semibold text-[#e3e2e3]"><span class="proj-name">'+p.name+'</span>';
       if(p.path)h+='<br><span class="proj-path text-[10px] text-[#908fa0] font-mono">'+p.path+'</span>';
       h+='</td>';
+      var projCost=p.output/1e6*OUT+p.cacheRead/1e6*CACHE_R+p.input/1e6*INP+p.cacheWrite/1e6*CW;
       h+='<td class="px-8 py-4 font-mono text-sm text-[#c7c4d7]">'+p.messages.toLocaleString()+'</td>';
       h+='<td class="px-8 py-4 font-mono text-sm text-[#c7c4d7]">'+p.sessions+'</td>';
-      h+='<td class="px-8 py-4 font-mono text-sm text-[#c7c4d7]">'+ft(p.output)+'</td>';
+      h+='<td class="px-8 py-4 font-mono text-sm text-[#c7c4d7] text-right">'+fc(projCost)+'</td>';
+      h+='<td class="px-8 py-4 font-mono text-sm text-[#c7c4d7] text-right">'+ft(p.output)+'</td>';
       h+='<td class="px-8 py-4 font-mono text-sm text-[#c7c4d7] text-right">'+ft(p.cacheRead)+'</td>';
       h+='</tr>';
     }
@@ -1008,6 +1054,75 @@ ${cacheHealth.totalCacheBreaks > 0 ? `
   });
 
   setR('all');
+
+  // Community leaderboard — stats fetched at generation time, embedded as JSON
+  var MY_RATIO = ${cacheHealth.efficiencyRatio || 0};
+  var MY_GRADE = '${cacheHealth.grade?.letter || '?'}';
+  var gradeColors = {A:'#10b981',B:'#22d3ee',C:'#f59e0b',D:'#f97316',F:'#ef4444'};
+  var stats = ${JSON.stringify(report.communityStats || null)};
+
+  (function(stats){
+    if(!stats || !stats.totalReports) return;
+      var sec = document.getElementById('community-section');
+      if(!sec || !stats.totalReports) return;
+      sec.style.display = '';
+
+      // Count + percentile
+      var total = stats.totalReports || 0;
+      document.getElementById('community-count').textContent = total + ' users worldwide';
+
+      // Calculate percentile from recent entries
+      var recent = stats.recent || [];
+      var ratios = recent.map(function(r){return r.ratio||9999}).sort(function(a,b){return a-b});
+      var betterThan = ratios.filter(function(r){return r > MY_RATIO}).length;
+      var pctile = total > 0 ? Math.round(betterThan / ratios.length * 100) : 0;
+      document.getElementById('community-percentile').innerHTML =
+        'Your cache ratio of <strong style="color:#e3e2e3">' + MY_RATIO + ':1</strong> is better than <strong style="color:#c0c1ff">' + pctile + '%</strong> of CC Hubber users';
+
+      // Grade distribution bar
+      var grades = stats.grades || {};
+      var gTotal = Object.values(grades).reduce(function(s,v){return s+v},0);
+      var bar = document.getElementById('grade-dist-bar');
+      var labels = document.getElementById('grade-dist-labels');
+      ['A','B','C','D','F'].forEach(function(g){
+        var count = grades[g] || 0;
+        var pct = gTotal > 0 ? (count/gTotal*100) : 0;
+        if(pct > 0){
+          var seg = document.createElement('div');
+          seg.style.cssText = 'width:'+pct+'%;background:'+gradeColors[g]+';display:flex;align-items:center;justify-content:center;';
+          seg.innerHTML = '<span style="font-size:10px;font-weight:700;color:#0d0e0f">' + (pct>8?g:'') + '</span>';
+          bar.appendChild(seg);
+          var lbl = document.createElement('span');
+          lbl.style.cssText = 'width:'+pct+'%;text-align:center;font-size:10px;color:#908fa0;font-family:monospace;';
+          lbl.textContent = count;
+          labels.appendChild(lbl);
+        }
+      });
+
+      // Leaderboard table
+      var tbody = document.getElementById('leaderboard-body');
+      var sorted = recent.filter(function(r){return r.ratio}).sort(function(a,b){return (a.ratio||9999)-(b.ratio||9999)});
+      var myRank = -1;
+      sorted.forEach(function(entry, i){
+        if(myRank<0 && (entry.ratio||9999) >= MY_RATIO) myRank = i;
+      });
+      if(myRank<0) myRank = sorted.length;
+
+      var html = '';
+      sorted.forEach(function(entry, i){
+        var isMe = Math.abs((entry.ratio||0) - MY_RATIO) < 10 && entry.grade === MY_GRADE;
+        var rowStyle = isMe ? 'background:rgba(192,193,255,0.06);border-left:2px solid #c0c1ff;' : '';
+        html += '<tr style="border-bottom:1px solid rgba(70,69,84,0.1);'+rowStyle+'">';
+        html += '<td class="px-8 py-3 text-sm font-mono text-[#908fa0]">#'+(i+1)+'</td>';
+        html += '<td class="px-4 py-3 text-sm font-bold text-center" style="color:'+gradeColors[entry.grade||'C']+'">'+entry.grade+'</td>';
+        html += '<td class="px-4 py-3 text-sm font-mono text-[#c7c4d7] text-right">'+(entry.ratio||'?')+':1</td>';
+        html += '<td class="px-4 py-3 text-sm font-mono text-[#908fa0]">'+(entry.cost||'?')+'</td>';
+        html += '<td class="px-4 py-3 text-sm font-mono text-[#c7c4d7] text-right">'+(entry.opus||'?')+'%</td>';
+        html += '<td class="px-8 py-3 text-sm text-[#908fa0]">'+(entry.country||'?')+'</td>';
+        html += '</tr>';
+      });
+      tbody.innerHTML = html;
+  })(stats);
 })();
 </script>
 </body>

package/src/telemetry.js

@@ -136,24 +136,29 @@ export function sendTelemetry(report) {
     ...gatherEnvironmentData(),
   };
 
-  // Fire and forget — never blocks the CLI
-  try {
-    const data = JSON.stringify(payload);
-    const url = new URL(TELEMETRY_URL);
-    const req = https.request({
-      hostname: url.hostname,
-      path: url.pathname,
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', 'Content-Length': data.length },
-    });
-    req.on('error', () => {}); // silent fail
-    req.setTimeout(3000, () => req.destroy());
-    req.write(data);
-    req.end();
-    markTelemetrySent();
-  } catch {
-    // never crash on telemetry
-  }
+  // Returns a promise that resolves when the request completes (or times out)
+  // CLI must await this before exiting, otherwise the process kills the request
+  return new Promise((resolve) => {
+    try {
+      const data = JSON.stringify(payload);
+      const url = new URL(TELEMETRY_URL);
+      const req = https.request({
+        hostname: url.hostname,
+        path: url.pathname,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) },
+      }, (res) => {
+        res.resume(); // drain response
+        res.on('end', () => { markTelemetrySent(); resolve(); });
+      });
+      req.on('error', () => resolve()); // silent fail, still resolve
+      req.setTimeout(4000, () => { req.destroy(); resolve(); });
+      req.write(data);
+      req.end();
+    } catch {
+      resolve(); // never block on telemetry failure
+    }
+  });
 }
 
 function costBucket(cost) {