cchubber 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +63 -60
  2. package/package.json +1 -1
  3. package/src/cli/index.js +2 -2
package/README.md CHANGED
@@ -1,24 +1,36 @@
1
1
  # CC Hubber
2
2
 
3
- **What you spent. Why you spent it. Is that normal.**
3
+ Your Claude Code usage, diagnosed. One command.
4
4
 
5
- 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.
5
+ ```bash
6
+ npx cchubber
7
+ ```
8
+
9
+ Reads your local data, generates an HTML report. No API keys, no telemetry, nothing leaves your machine.
10
+
11
+ 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.
12
+
13
+ ## What you get
6
14
 
7
- 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`.
15
+ A single HTML report that tells you three things: what you spent, why you spent it, and whether that's normal.
8
16
 
9
- ![CC Hubber Report](https://raw.githubusercontent.com/azkhh/cchubber/master/screenshot.png)
17
+ **The diagnosis:**
18
+ - Cache health grade (trend-weighted, recent 7 days count more)
19
+ - Inflection point detection: "Your efficiency dropped 3.2x starting March 17"
20
+ - Per-project cost breakdown with decoded project names
21
+ - Session intelligence: duration stats, tool usage, activity heatmap
22
+ - Model routing analysis (93% Opus? Your limits would last 3x longer on Sonnet)
23
+ - 8 actionable recommendations, each with estimated usage savings
10
24
 
11
- ## What it does
25
+ **The data:**
26
+ - Cost calculated from actual token counts (LiteLLM pricing, not the broken `costUSD` field)
27
+ - Message-level deduplication (Claude Code JSONL files contain ~50% duplicates from session resume)
28
+ - Subagent visibility: Haiku and Sonnet background agents show up in model distribution
29
+ - CLAUDE.md section-by-section analysis with per-message cost impact
30
+ - Cache break estimation even when diff files don't exist on your CC version
12
31
 
13
- - **Cost breakdown** — Per-day, per-model, per-project cost calculated from your actual token counts
14
- - **Cache health grade** — Trend-weighted (recent 7 days dominate). If you hit the cache bug, you'll see D/F, not a misleading A
15
- - **Inflection point detection** — "Your efficiency dropped 4.7x starting March 29. Before: 360:1. After: 1,676:1."
16
- - **Anomaly detection** — Flags days where your cost/ratio deviates >2 standard deviations
17
- - **Cache break analysis** — Reads `~/.claude/tmp/cache-break-*.diff` files. Shows why your cache broke and how often
18
- - **CLAUDE.md cost analysis** — How much your rules files cost per message (cached vs uncached)
19
- - **Per-project breakdown** — Which project is eating your budget
20
- - **Live rate limits** — 5-hour and 7-day utilization (if OAuth token available)
21
- - **Shareable card** — Export your report as a PNG
32
+ **The shareable card:**
33
+ 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.
22
34
 
23
35
  ## Install
24
36
 
@@ -26,74 +38,65 @@ Built because Claude Code users had zero visibility into the [March 2026 cache b
26
38
  npx cchubber
27
39
  ```
28
40
 
29
- Or install globally:
41
+ Or globally:
30
42
 
31
43
  ```bash
32
44
  npm install -g cchubber
33
45
  cchubber
34
46
  ```
35
47
 
36
- Requires Node.js 18+. Runs on macOS, Windows, and Linux.
48
+ Node.js 18+. Works on macOS, Windows, Linux.
37
49
 
38
- ## Usage
50
+ ## The cache bug (March 2026)
39
51
 
40
- ```bash
41
- cchubber # Scan and open HTML report
42
- cchubber --days 7 # Default view: last 7 days
43
- cchubber -o report.html # Custom output path
44
- cchubber --no-open # Don't auto-open in browser
45
- cchubber --json # Machine-readable JSON output
46
- ```
47
-
48
- ## What it reads
52
+ Between v2.1.69 and v2.1.89, five things broke at once:
49
53
 
50
- All data is local. Nothing leaves your machine.
54
+ 1. A sentinel replacement bug in Anthropic's custom Bun fork dropped cache read rates from 95% to 4-17%
55
+ 2. The `--resume` flag caused full prompt-cache misses on every single resume
56
+ 3. One session generated 652,069 output tokens with zero user input ($342 gone)
57
+ 4. Peak-hour throttling kicked in for 7% of users without announcement
58
+ 5. A 2x off-peak promotion expired, making the baseline feel like a cut
51
59
 
52
- | Source | Path | What |
53
- |--------|------|------|
54
- | JSONL conversations | `~/.claude/projects/*/` | Token counts per message, per model, per session |
55
- | Stats cache | `~/.claude/stats-cache.json` | Pre-aggregated daily totals |
56
- | Session meta | `~/.claude/usage-data/session-meta/` | Duration, tool counts, lines changed |
57
- | Cache breaks | `~/.claude/tmp/cache-break-*.diff` | Why your prompt cache invalidated |
58
- | CLAUDE.md stack | `~/.claude/CLAUDE.md`, project-level | File sizes and per-message cost impact |
59
- | OAuth usage | `~/.claude/.credentials.json` | Live rate limit utilization |
60
-
61
- ## The March 2026 cache bug
60
+ v2.1.90 fixes most of these. Run `claude update`.
62
61
 
63
- Between v2.1.69 and v2.1.89, multiple bugs caused Claude Code's prompt cache to silently fail:
62
+ 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.
64
63
 
65
- - A sentinel replacement bug in the Bun fork dropped cache read rates from ~95% to 4-17%
66
- - The `--resume` flag caused full prompt-cache misses on every resume
67
- - One session generated 652,069 output tokens with no user input — $342 on a single session
64
+ ## What the community figured out
68
65
 
69
- **v2.1.90 fixes most of these.** Update immediately: `claude update`
66
+ These tips came from GitHub issues, Reddit threads, and Twitter during the crisis. CC Hubber's recommendations are based on this data.
70
67
 
71
- 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.
68
+ - Start a fresh session for each task. Long sessions bleed tokens.
69
+ - Route subagents to Sonnet (`model: "sonnet"` on Task calls). Same quality, 5x cheaper per token.
70
+ - 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.
71
+ - Run `/compact` every 30-40 tool calls. Context bloat compounds.
72
+ - Create a `.claudeignore` file. Exclude `node_modules/`, `dist/`, `*.lock`. Saves tokens on every context load.
73
+ - Avoid `--resume` on older versions. Fixed in v2.1.90.
74
+ - Shift heavy work (refactors, test generation) outside 5am-11am PT. That's when Anthropic throttles session limits.
72
75
 
73
- ## Best practices (from the community)
76
+ ## How the cost works
74
77
 
75
- These tips surfaced during the March crisis. CC Hubber helps you verify whether they're working:
78
+ 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.
76
79
 
77
- - **Start fresh sessions per task** — don't try to extend long sessions
78
- - **Avoid `--resume` on older versions** — fixed in v2.1.90
79
- - **Switch to Sonnet 4.6 for routine work** — same quality, fraction of the quota
80
- - **Keep CLAUDE.md under 200 lines** — it's re-read on every message
81
- - **Use `/compact` every 30-40 tool calls** — prevents context bloat
82
- - **Create `.claudeignore`** — exclude `node_modules/`, `dist/`, `*.lock`
83
- - **Shift heavy work to off-peak hours** — outside 5am-11am PT weekdays
80
+ 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.
84
81
 
85
- ## How cost is calculated
82
+ ## Data sources
86
83
 
87
- 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.
84
+ Everything is local. CC Hubber reads files that already exist on your machine.
88
85
 
89
- 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.
86
+ | Source | Path | What it contains |
87
+ |--------|------|-----------------|
88
+ | Conversations | `~/.claude/projects/*/` | Token counts per message, per model |
89
+ | Subagents | `~/.claude/projects/*/subagents/` | Haiku/Sonnet background agent usage |
90
+ | Session meta | `~/.claude/usage-data/session-meta/` | Duration, tool counts, lines changed |
91
+ | Cache breaks | `~/.claude/tmp/cache-break-*.diff` | Why your prompt cache broke |
92
+ | CLAUDE.md | `~/.claude/CLAUDE.md` + project-level | File sizes, section breakdown, cost per message |
93
+ | Rate limits | `~/.claude/.credentials.json` | Live 5-hour and 7-day utilization |
90
94
 
91
- ## Prior art
95
+ ## Compared to ccusage
92
96
 
93
- - [ccusage](https://github.com/jikyo/ccusage) (12K+ stars) — token tracking and cost visualization
94
- - [Claude-Code-Usage-Monitor](https://github.com/nicobailon/Claude-Code-Usage-Monitor) — basic session tracking
97
+ [ccusage](https://github.com/ryoppippi/ccusage) (12K+ stars) is great for cost accounting. It tells you what you spent.
95
98
 
96
- 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.
99
+ 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.
97
100
 
98
101
  ## License
99
102
 
@@ -101,4 +104,4 @@ MIT
101
104
 
102
105
  ## Credits
103
106
 
104
- Built by [@azkhh](https://x.com/asmirkn). Shipped with [Mover OS](https://moveros.dev).
107
+ Built by [@azkhh](https://x.com/asmirkn). Shipped fast with [Mover OS](https://moveros.dev).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cchubber",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "What you spent. Why you spent it. Is that normal. — Claude Code usage diagnosis with beautiful HTML reports.",
5
5
  "type": "module",
6
6
  "bin": {
package/src/cli/index.js CHANGED
@@ -39,7 +39,7 @@ const flags = {
39
39
  if (flags.help) {
40
40
  console.log(`
41
41
  ╔═══════════════════════════════════════════════╗
42
- ║ CC Hubber v0.1.0 ║
42
+ ║ CC Hubber v0.3.1 ║
43
43
  ║ What you spent. Why you spent it. Is that ║
44
44
  ║ normal. ║
45
45
  ╚═══════════════════════════════════════════════╝
@@ -74,7 +74,7 @@ async function main() {
74
74
  process.exit(1);
75
75
  }
76
76
 
77
- console.log('\n CC Hubber v0.1.0');
77
+ console.log('\n CC Hubber v0.3.1');
78
78
  console.log(' ─────────────────────────────');
79
79
  console.log(' Reading local Claude Code data...\n');
80
80