cchubber 0.3.0 → 0.3.2

package/README.md

@@ -1,24 +1,36 @@
 # CC Hubber
 
-**What you spent. Why you spent it. Is that normal.**
+Your Claude Code usage, diagnosed. One command.
 
-Offline CLI that reads your local Claude Code data and generates a diagnostic HTML report. No API keys. No telemetry. Everything stays on your machine.
+```bash
+npx cchubber
+```
+
+Reads your local data, generates an HTML report. No API keys, no telemetry, nothing leaves your machine.
+
+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.
+
+## What you get
 
-Built because Claude Code users had zero visibility into the [March 2026 cache bug](https://github.com/anthropics/claude-code/issues/41930) that silently inflated costs by 10-20x. Your `$100 plan` shouldn't feel like a `$20 plan`.
+A single HTML report that tells you three things: what you spent, why you spent it, and whether that's normal.
 
-![CC Hubber Report](https://raw.githubusercontent.com/azkhh/cchubber/master/screenshot.png)
+**The diagnosis:**
+- Cache health grade (trend-weighted, recent 7 days count more)
+- Inflection point detection: "Your efficiency dropped 3.2x starting March 17"
+- Per-project cost breakdown with decoded project names
+- Session intelligence: duration stats, tool usage, activity heatmap
+- Model routing analysis (93% Opus? Your limits would last 3x longer on Sonnet)
+- 8 actionable recommendations, each with estimated usage savings
 
-## What it does
+**The data:**
+- Cost calculated from actual token counts (LiteLLM pricing, not the broken `costUSD` field)
+- Message-level deduplication (Claude Code JSONL files contain ~50% duplicates from session resume)
+- Subagent visibility: Haiku and Sonnet background agents show up in model distribution
+- CLAUDE.md section-by-section analysis with per-message cost impact
+- Cache break estimation even when diff files don't exist on your CC version
 
-- **Cost breakdown** — Per-day, per-model, per-project cost calculated from your actual token counts
-- **Cache health grade** — Trend-weighted (recent 7 days dominate). If you hit the cache bug, you'll see D/F, not a misleading A
-- **Inflection point detection** — "Your efficiency dropped 4.7x starting March 29. Before: 360:1. After: 1,676:1."
-- **Anomaly detection** — Flags days where your cost/ratio deviates >2 standard deviations
-- **Cache break analysis** — Reads `~/.claude/tmp/cache-break-*.diff` files. Shows why your cache broke and how often
-- **CLAUDE.md cost analysis** — How much your rules files cost per message (cached vs uncached)
-- **Per-project breakdown** — Which project is eating your budget
-- **Live rate limits** — 5-hour and 7-day utilization (if OAuth token available)
-- **Shareable card** — Export your report as a PNG
+**The shareable card:**
+An animated card with your grade, spend, cache ratio, and diagnosis line. Export as video. Post it. Let people see the numbers Anthropic won't show them.
 
 ## Install
 
@@ -26,74 +38,65 @@ Built because Claude Code users had zero visibility into the [March 2026 cache b
 npx cchubber
 ```
 
-Or install globally:
+Or globally:
 
 ```bash
 npm install -g cchubber
 cchubber
 ```
 
-Requires Node.js 18+. Runs on macOS, Windows, and Linux.
+Node.js 18+. Works on macOS, Windows, Linux.
 
-## Usage
+## The cache bug (March 2026)
 
-```bash
-cchubber                      # Scan and open HTML report
-cchubber --days 7             # Default view: last 7 days
-cchubber -o report.html       # Custom output path
-cchubber --no-open            # Don't auto-open in browser
-cchubber --json               # Machine-readable JSON output
-```
-
-## What it reads
+Between v2.1.69 and v2.1.89, five things broke at once:
 
-All data is local. Nothing leaves your machine.
+1. A sentinel replacement bug in Anthropic's custom Bun fork dropped cache read rates from 95% to 4-17%
+2. The `--resume` flag caused full prompt-cache misses on every single resume
+3. One session generated 652,069 output tokens with zero user input ($342 gone)
+4. Peak-hour throttling kicked in for 7% of users without announcement
+5. A 2x off-peak promotion expired, making the baseline feel like a cut
 
-| Source | Path | What |
-|--------|------|------|
-| JSONL conversations | `~/.claude/projects/*/` | Token counts per message, per model, per session |
-| Stats cache | `~/.claude/stats-cache.json` | Pre-aggregated daily totals |
-| Session meta | `~/.claude/usage-data/session-meta/` | Duration, tool counts, lines changed |
-| Cache breaks | `~/.claude/tmp/cache-break-*.diff` | Why your prompt cache invalidated |
-| CLAUDE.md stack | `~/.claude/CLAUDE.md`, project-level | File sizes and per-message cost impact |
-| OAuth usage | `~/.claude/.credentials.json` | Live rate limit utilization |
-
-## The March 2026 cache bug
+v2.1.90 fixes most of these. Run `claude update`.
 
-Between v2.1.69 and v2.1.89, multiple bugs caused Claude Code's prompt cache to silently fail:
+CC Hubber shows you whether you were affected. If your report has a sharp inflection point around mid-March, that's probably when it hit you.
 
-- A sentinel replacement bug in the Bun fork dropped cache read rates from ~95% to 4-17%
-- The `--resume` flag caused full prompt-cache misses on every resume
-- One session generated 652,069 output tokens with no user input — $342 on a single session
+## What the community figured out
 
-**v2.1.90 fixes most of these.** Update immediately: `claude update`
+These tips came from GitHub issues, Reddit threads, and Twitter during the crisis. CC Hubber's recommendations are based on this data.
 
-CC Hubber detects whether you were affected by showing your cache efficiency trend over time. If you see a sharp inflection point, that's probably when it hit you.
+- Start a fresh session for each task. Long sessions bleed tokens.
+- Route subagents to Sonnet (`model: "sonnet"` on Task calls). Same quality, 5x cheaper per token.
+- Keep your CLAUDE.md under 200 lines. It gets re-read on every message. 12K tokens at 200 messages/day costs $1.23/day cached.
+- Run `/compact` every 30-40 tool calls. Context bloat compounds.
+- Create a `.claudeignore` file. Exclude `node_modules/`, `dist/`, `*.lock`. Saves tokens on every context load.
+- Avoid `--resume` on older versions. Fixed in v2.1.90.
+- Shift heavy work (refactors, test generation) outside 5am-11am PT. That's when Anthropic throttles session limits.
 
-## Best practices (from the community)
+## How the cost works
 
-These tips surfaced during the March crisis. CC Hubber helps you verify whether they're working:
+Claude Code doesn't show costs for Max and Pro plans (`costUSD` is always 0). CC Hubber calculates equivalent API cost from your token counts using LiteLLM's pricing data.
 
-- **Start fresh sessions per task** — don't try to extend long sessions
-- **Avoid `--resume` on older versions** — fixed in v2.1.90
-- **Switch to Sonnet 4.6 for routine work** — same quality, fraction of the quota
-- **Keep CLAUDE.md under 200 lines** — it's re-read on every message
-- **Use `/compact` every 30-40 tool calls** — prevents context bloat
-- **Create `.claudeignore`** — exclude `node_modules/`, `dist/`, `*.lock`
-- **Shift heavy work to off-peak hours** — outside 5am-11am PT weekdays
+The number you see is what you'd pay on the API tier for the same usage. Useful for comparing consumption across days and projects. Not a billing statement.
 
-## How cost is calculated
+## Data sources
 
-Claude Code doesn't report costs for Max/Pro plans (`costUSD` is always 0). CC Hubber calculates costs from token counts using dynamic pricing from [LiteLLM](https://github.com/BerriAI/litellm), with hardcoded fallbacks.
+Everything is local. CC Hubber reads files that already exist on your machine.
 
-This gives you an **equivalent API cost** — what you would pay on the API tier for the same usage. Useful for understanding relative consumption, not for billing disputes.
+| Source | Path | What it contains |
+|--------|------|-----------------|
+| Conversations | `~/.claude/projects/*/` | Token counts per message, per model |
+| Subagents | `~/.claude/projects/*/subagents/` | Haiku/Sonnet background agent usage |
+| Session meta | `~/.claude/usage-data/session-meta/` | Duration, tool counts, lines changed |
+| Cache breaks | `~/.claude/tmp/cache-break-*.diff` | Why your prompt cache broke |
+| CLAUDE.md | `~/.claude/CLAUDE.md` + project-level | File sizes, section breakdown, cost per message |
+| Rate limits | `~/.claude/.credentials.json` | Live 5-hour and 7-day utilization |
 
-## Prior art
+## Compared to ccusage
 
-- [ccusage](https://github.com/jikyo/ccusage) (12K+ stars) — token tracking and cost visualization
-- [Claude-Code-Usage-Monitor](https://github.com/nicobailon/Claude-Code-Usage-Monitor) — basic session tracking
+[ccusage](https://github.com/ryoppippi/ccusage) (12K+ stars) is great for cost accounting. It tells you what you spent.
 
-CC Hubber focuses on **diagnosis** — cache health grading, inflection detection, cache break analysis — not just accounting. If ccusage tells you *what* you spent, CC Hubber tells you *why* and whether it's normal.
+CC Hubber tells you why, and whether it's normal. Inflection detection, cache break estimation, model routing savings, session intelligence, trend-weighted grading. Different tools for different questions.
 
 ## License
 
@@ -101,4 +104,4 @@ MIT
 
 ## Credits
 
-Built by [@azkhh](https://x.com/asmirkn). Shipped with [Mover OS](https://moveros.dev).
+Built by [@azkhh](https://x.com/asmirkn). Shipped fast with [Mover OS](https://moveros.dev).

package/package.json

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

package/src/cli/index.js

@@ -20,11 +20,13 @@ 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';
+import { shouldSendTelemetry, sendTelemetry } from '../telemetry.js';
 
 const args = process.argv.slice(2);
 const flags = {
   help: args.includes('--help') || args.includes('-h'),
   json: args.includes('--json'),
+  noTelemetry: args.includes('--no-telemetry'),
   noOpen: args.includes('--no-open'),
   output: (() => {
     const idx = args.indexOf('--output') !== -1 ? args.indexOf('--output') : args.indexOf('-o');
@@ -39,7 +41,7 @@ const flags = {
 if (flags.help) {
   console.log(`
   ╔═══════════════════════════════════════════════╗
-  ║              CC Hubber v0.1.0                 ║
+  ║              CC Hubber v0.3.1                 ║
   ║  What you spent. Why you spent it. Is that    ║
   ║  normal.                                      ║
   ╚═══════════════════════════════════════════════╝
@@ -74,7 +76,7 @@ async function main() {
     process.exit(1);
   }
 
-  console.log('\n  CC Hubber v0.1.0');
+  console.log('\n  CC Hubber v0.3.1');
   console.log('  ─────────────────────────────');
   console.log('  Reading local Claude Code data...\n');
 
@@ -149,6 +151,12 @@ async function main() {
 
   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)');
+  }
+
   const outputPath = flags.output || join(process.cwd(), 'cchubber-report.html');
   const html = renderHTML(report);
   writeFileSync(outputPath, html, 'utf-8');

package/src/telemetry.js

@@ -0,0 +1,122 @@
+import https from 'https';
+import { platform, arch } from 'os';
+
+// Anonymous usage telemetry — no PII, no tokens, no file contents.
+// Opt out: npx cchubber --no-telemetry
+// Or set env: CC_HUBBER_TELEMETRY=0
+
+const TELEMETRY_URL = process.env.CC_HUBBER_TELEMETRY_URL || 'https://cchubber-telemetry.azkhh.workers.dev/collect';
+
+export function shouldSendTelemetry(flags) {
+  if (flags.noTelemetry) return false;
+  if (process.env.CC_HUBBER_TELEMETRY === '0') return false;
+  if (process.env.DO_NOT_TRACK === '1') return false;
+  return true;
+}
+
+export function sendTelemetry(report) {
+  const payload = {
+    v: '0.3.1',
+    ts: new Date().toISOString(),
+    os: platform(),
+    arch: arch(),
+
+    // Aggregated stats — no file contents, no project names, no personal data
+    // Usage profile
+    grade: report.cacheHealth?.grade?.letter || '?',
+    cacheRatio: report.cacheHealth?.efficiencyRatio || 0,
+    cacheHitRate: report.cacheHealth?.cacheHitRate || 0,
+    cacheBreaks: report.cacheHealth?.totalCacheBreaks || 0,
+    estimatedBreaks: report.cacheHealth?.estimatedBreaks || 0,
+    cacheSaved: report.cacheHealth?.savings?.fromCaching || 0,
+    cacheWasted: report.cacheHealth?.savings?.wastedFromBreaks || 0,
+
+    // Cost & scale
+    activeDays: report.costAnalysis?.activeDays || 0,
+    totalCostBucket: costBucket(report.costAnalysis?.totalCost || 0),
+    avgDailyCost: Math.round(report.costAnalysis?.avgDailyCost || 0),
+    peakDayCost: Math.round(report.costAnalysis?.peakDay?.cost || 0),
+    totalMessages: report.costAnalysis?.dailyCosts?.reduce((s, d) => s + (d.messageCount || 0), 0) || 0,
+
+    // Model usage (key for understanding subscription behavior)
+    modelSplit: modelSplitSummary(report.costAnalysis?.modelCosts || {}),
+    modelCount: Object.keys(report.costAnalysis?.modelCosts || {}).length,
+    opusPct: report.modelRouting?.opusPct || 0,
+    sonnetPct: report.modelRouting?.sonnetPct || 0,
+    haikuPct: report.modelRouting?.haikuPct || 0,
+    subagentPct: report.modelRouting?.subagentPct || 0,
+
+    // CLAUDE.md (how people configure their AI)
+    claudeMdTokens: report.claudeMdStack?.totalTokensEstimate || 0,
+    claudeMdBytes: report.claudeMdStack?.totalBytes || 0,
+    claudeMdSections: report.claudeMdStack?.globalSections?.length || 0,
+    claudeMdFiles: report.claudeMdStack?.files?.length || 0,
+    claudeMdCostCached: report.claudeMdStack?.costPerMessage?.cached || 0,
+    claudeMdCostUncached: report.claudeMdStack?.costPerMessage?.uncached || 0,
+
+    // Session patterns (how people work)
+    sessionCount: report.sessionIntel?.totalSessions || 0,
+    avgSessionMin: report.sessionIntel?.avgDuration || 0,
+    medianSessionMin: report.sessionIntel?.medianDuration || 0,
+    p90SessionMin: report.sessionIntel?.p90Duration || 0,
+    maxSessionMin: report.sessionIntel?.maxDuration || 0,
+    longSessionPct: report.sessionIntel?.longSessionPct || 0,
+    avgToolsPerSession: report.sessionIntel?.avgToolsPerSession || 0,
+    linesPerHour: report.sessionIntel?.linesPerHour || 0,
+    peakOverlapPct: report.sessionIntel?.peakOverlapPct || 0,
+    topTools: (report.sessionIntel?.topTools || []).slice(0, 6).map(t => t.name),
+
+    // Scale indicators
+    projectCount: report.projectBreakdown?.length || 0,
+    anomalyCount: report.anomalies?.anomalies?.length || 0,
+    trend: report.anomalies?.trend || 'stable',
+    inflectionDir: report.inflection?.direction || 'none',
+    inflectionMult: report.inflection?.multiplier || 0,
+    entryCount: report.costAnalysis?.dailyCosts?.length || 0,
+    recCount: report.recommendations?.length || 0,
+
+    // Rate limits (if available — shows subscription tier indirectly)
+    hasOauth: !!report.oauthUsage,
+    rateLimit5h: report.oauthUsage?.five_hour?.utilization || null,
+    rateLimit7d: report.oauthUsage?.seven_day?.utilization || null,
+  };
+
+  // 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();
+  } catch {
+    // never crash on telemetry
+  }
+}
+
+function costBucket(cost) {
+  // Bucketed so we can't identify individuals by exact cost
+  if (cost < 10) return '<10';
+  if (cost < 50) return '10-50';
+  if (cost < 200) return '50-200';
+  if (cost < 500) return '200-500';
+  if (cost < 1000) return '500-1K';
+  if (cost < 5000) return '1K-5K';
+  return '5K+';
+}
+
+function modelSplitSummary(modelCosts) {
+  const total = Object.values(modelCosts).reduce((s, c) => s + c, 0);
+  if (total === 0) return {};
+  const split = {};
+  for (const [name, cost] of Object.entries(modelCosts)) {
+    split[name] = Math.round((cost / total) * 100);
+  }
+  return split;
+}