v0.3.4 — Six-tier ladder + cache cost-accuracy fixes + offline UI
A mix of a user-visible product change (the tokenmaxx tier rename + expansion) and three credibility-grade infrastructure fixes — two for cost accuracy on the cache path, one for the local-first promise.
TokenMaxx ladder expanded to 6 tiers
The top tier was previously TokenGigaChad at 20×+ — but almost every Claude Code power user lands there, so the headline lost its bite. Two changes:
- Top tier raised to 50×+ so it reflects genuinely extreme usage, not everyday heavy use
- New tier in the middle for the 20–50× range
- Top two tiers renamed to drop the Chad branding
| Multiplier (subscription users) | Absolute /mo (API users) | Tier |
|---|---|---|
| < 1× | < $100 | 💧 TokenSipper |
| 1× – 4× | $100 – $400 | 🥱 TokenModerator |
| 4× – 10× | $400 – $1,000 | 💸 TokenMaxxer |
| 10× – 20× | $1,000 – $2,000 | 🔥 TokenSuperMaxxer (was TokenChad) |
| 20× – 50× | $2,000 – $5,000 | 🔥🔥 TokenMegaMaxxer (new) |
| 50×+ | $5,000+ | 🔥🔥🔥 TokenGigaMaxxer (was TokenGigaChad) |
Breaking note: the JSON output's `tier` field carries the new label string verbatim. Any consumer scripting against `TokenChad` / `TokenGigaChad` in `tj tokenmaxx --json` must update.
Cost-accuracy fixes (cache path)
Two related cache-billing fixes from community contributor @sjhddh, plus a follow-up to persist the raw counts.
Cache-only spans no longer costed at $0
A prompt-cache hit (`input_tokens=0`, `output_tokens=0`, but `cache_read_tokens > 0`) bills the cache-read rate, but `calculate_cost()` and `CostEngine.process_span()` were short-circuiting on input/output token counts alone — dropping the span as a no-op. The better your caching, the more cost went missing. The early-return guards now check all four token counts. (PR #90, kudos @sjhddh.)
Cache-creation tokens now costed on the live OTLP ingest path
The SDK integrations emit `gen_ai.usage.cache_creation_tokens` and the pricing table carried a `cache_write_per_mtok` rate, but the live parsers (`parse_otlp_span` + `convert_otel_span`) only read cache-read tokens. So every cache-write emitted via SDK was silently dropped, and the higher-rate cost never charged. `NormalizedSpan` now carries `cache_write_tokens`; both parsers populate it; `process_span` charges it. (PR #92, also @sjhddh.)
`cache_write_tokens` now persisted and threaded everywhere
- New `cache_write_tokens` column on the `spans` table (migration 5)
- The 3 remaining ingest paths (Langfuse, Helicone, Claude Code log adapter) now thread cache-creation tokens through `NormalizedSpan` for consistency with the live OTLP path
- Codex's `cached_token_count` deliberately not mapped to `cache_write` — OpenAI's automatic prompt caching only bills cache-reads at a discount and has no separate cache-creation billing
The `cache` analyzer can now compute creation vs read breakdowns from real data. (PR #95, closes #93 + #94.)
Web UI works fully offline
The `tj serve` dashboard at `http://127.0.0.1:7391/\` was loading three things from external CDNs at render time, which broke the "local-first, no data egress" promise for any user running TokenJam in an air-gapped environment to verify exactly that claim:
- Favicon SVG from `tokenjam.dev` → now inlined as a `data:` URL
- Geist + Geist Mono fonts from `fonts.googleapis.com` → removed; system-font fallbacks already in CSS
- Preact + hooks + htm from `esm.sh` → vendored under `tokenjam/ui/vendor/`, served via FastAPI `StaticFiles`, wired up via `<script type="importmap">` (JS source unchanged)
New regression tests catch any future external-URL slip. (PR #88, closes #87.)
`pipx install tokenjam` is the recommended install path
`pip install tokenjam` failed on macOS with Homebrew Python (PEP 668) and Debian 12+ / Ubuntu 24+. The unhelpful error broke the 3-command quickstart flow promised on `tokenjam.dev/tokenmaxxing`. All install snippets across the README, `docs/`, blog tutorials, and `examples/` now lead with `pipx install tokenjam`. Cross-platform pipx-install fallback table includes macOS / Debian/Ubuntu / Windows / generic. (PR #88 + PR #89, closes #86.)
Install
```
pipx install tokenjam==0.3.4
```
TypeScript SDK in lockstep as `@tokenjam/sdk@0.3.4`.
Thanks to @sjhddh for two excellent cost-accuracy fixes (PRs #90 + #92) and to everyone who flagged install + offline-UI issues during the 0.3.x rollout.
