cchubber 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cchubber",
-  "version": "0.1.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/model-routing.js

@@ -0,0 +1,72 @@
+/**
+ * Model Routing Analysis
+ * Detects model usage patterns and estimates savings from better routing.
+ */
+export function analyzeModelRouting(costAnalysis, jsonlEntries) {
+  const modelCosts = costAnalysis.modelCosts || {};
+  const totalCost = Object.values(modelCosts).reduce((s, c) => s + c, 0);
+
+  if (totalCost < 0.01) return { available: false };
+
+  // Classify models into tiers
+  const tiers = { opus: 0, sonnet: 0, haiku: 0, other: 0 };
+  const tierCosts = { opus: 0, sonnet: 0, haiku: 0, other: 0 };
+
+  for (const [name, cost] of Object.entries(modelCosts)) {
+    const lower = name.toLowerCase();
+    if (lower.includes('opus')) { tiers.opus++; tierCosts.opus += cost; }
+    else if (lower.includes('sonnet')) { tiers.sonnet++; tierCosts.sonnet += cost; }
+    else if (lower.includes('haiku')) { tiers.haiku++; tierCosts.haiku += cost; }
+    else { tiers.other++; tierCosts.other += cost; }
+  }
+
+  const opusPct = totalCost > 0 ? Math.round((tierCosts.opus / totalCost) * 100) : 0;
+  const sonnetPct = totalCost > 0 ? Math.round((tierCosts.sonnet / totalCost) * 100) : 0;
+  const haikuPct = totalCost > 0 ? Math.round((tierCosts.haiku / totalCost) * 100) : 0;
+
+  // Estimate savings: assume 40% of Opus work could be done by Sonnet at 60% cost
+  // Conservative estimate — Sonnet handles file reads, simple edits, search well
+  const opusCost = tierCosts.opus;
+  const routableToSonnet = opusCost * 0.4; // 40% of Opus work is routable
+  const sonnetEquivalentCost = routableToSonnet * 0.6; // Sonnet is ~60% of Opus cost
+  const estimatedSavings = routableToSonnet - sonnetEquivalentCost;
+
+  // Detect subagent usage from JSONL (subagent messages often use different models)
+  let subagentMessages = 0;
+  let mainMessages = 0;
+  if (jsonlEntries && jsonlEntries.length > 0) {
+    for (const entry of jsonlEntries) {
+      const model = (entry.model || '').toLowerCase();
+      // Subagents typically use sonnet/haiku, main thread uses opus
+      if (model.includes('sonnet') || model.includes('haiku')) {
+        subagentMessages++;
+      } else {
+        mainMessages++;
+      }
+    }
+  }
+
+  const subagentPct = (subagentMessages + mainMessages) > 0
+    ? Math.round((subagentMessages / (subagentMessages + mainMessages)) * 100)
+    : 0;
+
+  // Model diversity score (0-100): higher = better routing
+  const modelCount = Object.keys(modelCosts).length;
+  let diversityScore = 0;
+  if (modelCount >= 3 && opusPct < 80) diversityScore = 90;
+  else if (modelCount >= 2 && opusPct < 90) diversityScore = 60;
+  else if (opusPct > 95) diversityScore = 20;
+  else diversityScore = 40;
+
+  return {
+    available: true,
+    opusPct,
+    sonnetPct,
+    haikuPct,
+    estimatedSavings: Math.round(estimatedSavings),
+    subagentPct,
+    diversityScore,
+    tierCosts,
+    totalCost,
+  };
+}

package/src/analyzers/recommendations.js

@@ -1,128 +1,162 @@
-export function generateRecommendations(costAnalysis, cacheHealth, claudeMdStack, anomalies, inflection) {
+/**
+ * Recommendations Engine
+ * 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, goes first
+  // 0. Inflection point
   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.',
+      title: `Cache efficiency dropped ${inflection.multiplier}x on ${inflection.date}`,
+      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: 'Something changed for the better on this date. Likely a version update or workflow change.',
+      savings: 'Already saving',
+      action: 'Your cache efficiency improved. Likely a version update or workflow change.',
     });
   }
 
-  // 1. CLAUDE.md size
+  // 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;
+
+  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.`,
+    });
+  }
+
+  // 2. CLAUDE.md bloat
   if (claudeMdStack.totalTokensEstimate > 8000) {
+    const excessK = Math.round((claudeMdStack.totalTokensEstimate - 4000) / 1000);
+    recs.push({
+      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.',
+    });
+  }
+
+  // 3. Compaction frequency — community's #1 session management tip
+  if (sessionIntel?.available && sessionIntel.avgToolsPerSession > 25) {
     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.',
+      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.',
     });
   }
 
-  // 2. Cache break frequency
-  if (cacheHealth.totalCacheBreaks > 10) {
-    const topReason = cacheHealth.reasonsRanked[0];
+  // 4. Fresh sessions per task
+  if (sessionIntel?.available && sessionIntel.longSessionPct > 30) {
     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.',
+      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.`,
     });
   }
 
-  // 3. High cache:output ratio
-  if (cacheHealth.efficiencyRatio > 2000) {
+  // 5. Cache ratio warning
+  if (cacheHealth.efficiencyRatio > 1500) {
     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.',
+      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 > 1000) {
+  } else if (cacheHealth.efficiencyRatio > 800) {
     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.',
+      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.',
     });
   }
 
-  // 4. Cost anomalies
+  // 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.',
+    });
+  }
+
+  // 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');
     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.',
+        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.',
       });
     }
   }
 
-  // 5. Cost trend
-  if (anomalies.trend === 'rising_fast') {
+  // 9. Avoid --resume on older versions
+  if (cacheHealth.efficiencyRatio > 600) {
     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.',
+      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.',
     });
   }
 
-  // 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;
+  // 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.',
+  });
 
-  if (opusPercentage > 90) {
+  // 11. Disconnect unused MCP tools
+  if (sessionIntel?.available && sessionIntel.topTools.some(t => t.name.includes('mcp__'))) {
     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.',
+      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.',
     });
   }
 
-  // 8. Caching savings acknowledgment
-  if (cacheHealth.savings.fromCaching > 100) {
+  // 12. Cache savings (positive)
+  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.',
+      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.',
     });
   }
 
-  return recs;
+  return recs.slice(0, 8);
 }

package/src/analyzers/session-intelligence.js

@@ -0,0 +1,114 @@
+/**
+ * Session Intelligence
+ * Analyzes session patterns: length, tool density, compact usage, productivity.
+ */
+export function analyzeSessionIntelligence(sessionMeta, jsonlEntries) {
+  if (!sessionMeta || sessionMeta.length === 0) {
+    return { available: false };
+  }
+
+  const sessions = sessionMeta.filter(s => s.durationMinutes > 0);
+  if (sessions.length === 0) return { available: false };
+
+  // Basic session stats
+  const durations = sessions.map(s => s.durationMinutes);
+  const totalMinutes = durations.reduce((s, d) => s + d, 0);
+  const avgDuration = totalMinutes / sessions.length;
+  const maxDuration = Math.max(...durations);
+  const longestSession = sessions.find(s => s.durationMinutes === maxDuration);
+
+  // Sort by duration for percentile calc
+  const sorted = [...durations].sort((a, b) => a - b);
+  const p50 = sorted[Math.floor(sorted.length * 0.5)];
+  const p90 = sorted[Math.floor(sorted.length * 0.9)];
+
+  // Long sessions (>60 min) — likely need /compact
+  const longSessions = sessions.filter(s => s.durationMinutes > 60);
+  const longSessionPct = sessions.length > 0 ? Math.round((longSessions.length / sessions.length) * 100) : 0;
+
+  // Tool call density per session
+  const toolDensities = sessions.map(s => {
+    const totalTools = Object.values(s.toolCounts || {}).reduce((sum, c) => sum + c, 0);
+    return { sessionId: s.sessionId, tools: totalTools, minutes: s.durationMinutes, density: s.durationMinutes > 0 ? (totalTools / s.durationMinutes).toFixed(1) : 0 };
+  });
+
+  const avgToolsPerSession = toolDensities.reduce((s, t) => s + t.tools, 0) / sessions.length;
+
+  // Most used tools across all sessions
+  const toolTotals = {};
+  for (const s of sessions) {
+    for (const [tool, count] of Object.entries(s.toolCounts || {})) {
+      toolTotals[tool] = (toolTotals[tool] || 0) + count;
+    }
+  }
+  const topTools = Object.entries(toolTotals)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 8)
+    .map(([name, count]) => ({ name, count }));
+
+  // Lines of code per session hour (productivity proxy)
+  const totalLines = sessions.reduce((s, x) => s + x.linesAdded + x.linesRemoved, 0);
+  const totalHours = totalMinutes / 60;
+  const linesPerHour = totalHours > 0 ? Math.round(totalLines / totalHours) : 0;
+
+  // Messages per session
+  const totalMessages = sessions.reduce((s, x) => s + x.userMessageCount + x.assistantMessageCount, 0);
+  const avgMessagesPerSession = Math.round(totalMessages / sessions.length);
+
+  // Time-of-day distribution (from JSONL timestamps)
+  const hourDistribution = new Array(24).fill(0);
+  if (jsonlEntries && jsonlEntries.length > 0) {
+    for (const entry of jsonlEntries) {
+      if (!entry.timestamp) continue;
+      try {
+        const d = new Date(entry.timestamp);
+        if (!isNaN(d.getTime())) {
+          hourDistribution[d.getHours()]++;
+        }
+      } catch { /* skip */ }
+    }
+  }
+
+  // Peak hours (top 3)
+  const peakHours = hourDistribution
+    .map((count, hour) => ({ hour, count }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 3)
+    .map(h => ({ hour: h.hour, label: formatHour(h.hour), count: h.count }));
+
+  // Off-peak overlap check (5am-11am PT = 12pm-6pm UTC, roughly)
+  const offPeakStart = 12; // UTC
+  const offPeakEnd = 18;
+  const peakOverlapMessages = hourDistribution
+    .slice(offPeakStart, offPeakEnd + 1)
+    .reduce((s, c) => s + c, 0);
+  const totalHourMessages = hourDistribution.reduce((s, c) => s + c, 0);
+  const peakOverlapPct = totalHourMessages > 0 ? Math.round((peakOverlapMessages / totalHourMessages) * 100) : 0;
+
+  return {
+    available: true,
+    totalSessions: sessions.length,
+    totalMinutes,
+    avgDuration: Math.round(avgDuration),
+    medianDuration: p50,
+    p90Duration: p90,
+    maxDuration,
+    longestSessionProject: longestSession?.projectPath,
+    longSessions: longSessions.length,
+    longSessionPct,
+    avgToolsPerSession: Math.round(avgToolsPerSession),
+    topTools,
+    linesPerHour,
+    avgMessagesPerSession,
+    peakHours,
+    peakOverlapPct,
+    hourDistribution,
+  };
+}
+
+function formatHour(h) {
+  if (h === 0) return '12am';
+  if (h < 12) return h + 'am';
+  if (h === 12) return '12pm';
+  return (h - 12) + 'pm';
+}

package/src/cli/index.js

@@ -16,6 +16,8 @@ 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 { analyzeSessionIntelligence } from '../analyzers/session-intelligence.js';
+import { analyzeModelRouting } from '../analyzers/model-routing.js';
 import { renderHTML } from '../renderers/html-report.js';
 import { renderTerminal } from '../renderers/terminal-summary.js';
 
@@ -115,21 +117,24 @@ async function main() {
   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}`);
-  }
+  const sessionIntel = analyzeSessionIntelligence(sessionMeta, jsonlEntries);
+  const modelRouting = analyzeModelRouting(costAnalysis, jsonlEntries);
+  const recommendations = generateRecommendations(costAnalysis, cacheHealth, claudeMdStack, anomalies, inflection, sessionIntel, modelRouting);
 
+  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`);
 
   const report = {
     generatedAt: new Date().toISOString(),
-    periodDays: flags.days, // Default view in HTML
+    periodDays: flags.days,
     costAnalysis,
     cacheHealth,
     anomalies,
     inflection,
+    sessionIntel,
+    modelRouting,
     projectBreakdown,
     claudeMdStack,
     oauthUsage,

package/src/readers/claude-md.js

@@ -6,15 +6,40 @@ export function readClaudeMdStack(claudeDir) {
   const home = homedir();
   const stack = [];
 
-  // Global CLAUDE.md
+  // Global CLAUDE.md — detailed section analysis
   const globalPath = join(home, '.claude', 'CLAUDE.md');
+  let globalSections = [];
   if (existsSync(globalPath)) {
     const stat = statSync(globalPath);
+    const content = readFileSync(globalPath, 'utf-8');
+    const lines = content.split('\n');
+    const lineCount = lines.length;
+
+    // Parse sections (## headings)
+    let currentSection = { name: 'Header', lines: 0, bytes: 0 };
+    const sections = [];
+    for (const line of lines) {
+      if (line.match(/^##\s+/)) {
+        if (currentSection.lines > 0) sections.push(currentSection);
+        currentSection = { name: line.replace(/^#+\s*/, '').trim(), lines: 0, bytes: 0 };
+      }
+      currentSection.lines++;
+      currentSection.bytes += Buffer.byteLength(line + '\n', 'utf-8');
+    }
+    if (currentSection.lines > 0) sections.push(currentSection);
+
+    // Add token estimates, keep original file order (don't sort)
+    globalSections = sections
+      .map((s, idx) => ({ ...s, tokens: Math.round(s.bytes / 4), order: idx }));
+
     stack.push({
       level: 'global',
       path: globalPath,
       bytes: stat.size,
       tokensEstimate: Math.round(stat.size / 4),
+      lineCount,
+      sectionCount: sections.length,
+      sections: globalSections,
     });
   }
 
@@ -54,6 +79,7 @@ export function readClaudeMdStack(claudeDir) {
 
   return {
     files: stack,
+    globalSections,
     totalBytes,
     totalTokensEstimate,
     settingsBytes: settingsSize,