TokenJam reads your Claude Code, Codex, and other agent logs and estimates where you can cut tokens: cheaper models, cacheable prefixes, leaner prompts, deterministic scripts.
Open-source. Runs locally. Full observability stack included.
$ pipx install tokenjaminstalled tokenjam · CLI available as `tj` or `tokenjam` $ tj onboard --claude-codewired Claude Code telemetry · backfilled 247 sessions $ tj optimizeAnalyzing 247 sessions, 9.8K spans, 4.0M tokens (30d)… downsize 116 sessions look Haiku-eligible (structural) cache 2.4K-token prefix repeats across 94% of calls trim ~770 low-significance tokens in your CLAUDE.md Estimated recoverable: ~$1,632/mo — review before acting $ tj tokenmaxx Efficiency tier: LeanOperator · 38% overhead this cycle
Illustrative output. Every figure is an estimate you review before acting.
Telemetry from your agents flows into the TokenJam core, through the analyzers, and out to TokenJam Lens and TokenJam Bench.
From your agents
Reads telemetry from every major agent runtime, framework, provider, and observability tool.
Each analyzer reads the same captured telemetry and surfaces a different shape of waste. Lens brings them together in a local dashboard you can open in your browser.
Find tasks where a cheaper model would suffice.
$ tj optimize Analyzing 247 sessions, 9.8K spans, 4.0M tokens (last 30d)… ① Model downgrade: 47% of sessions look Haiku-eligible • 116 of 247 sessions match structural heuristics • Currently: claude-opus-4-7, claude-sonnet-4-7 • Suggested target: claude-haiku-4-5 • At current usage: $1,886 → $254 (-86% on flagged sessions) • Estimated monthly savings: $1,632 (-38% total)
Identify token waste in your system prompts.
Prompt bloat detected in claude-code-myproj: • Your CLAUDE.md is 4,213 tokens (up 38% in 30 days) • Section "Coding conventions > Error handling" appears identically in 91 of 247 sessions (1,108 tokens × 91 = ~100K repeated tokens) • Significance analysis suggests ~340 of those 1,108 tokens carry the signal; the rest could be trimmed • Estimated cost: ~$8.50/mo at current usage on Sonnet
Detect cacheable prompt prefixes. Save 30–60% with provider-native caching.
Cache opportunities in last 30d: • Identical 2,400-token prefix detected across 94% of your calls (your CLAUDE.md + tools + system prompt) → You're already using prompt caching for 11% of cacheable opportunities. → Increasing cache_control breakpoints could save ~$42/mo (90% reduction on the 89% of calls currently paying full price). • Semantic similarity ≥0.95 detected on 47 instances of "format SQL query" style requests in last 30d. → Estimated savings: $8/mo at TTL ≥ 1 day.
Surface recurring agent sessions that should have been simple (deterministic) scripts.
Deterministic workflow candidates (high confidence only): • 23 sessions in last 30d executed identical 5-step sequence: git pull → npm install → cat .env.staging → npm run build → pm2 restart Zero argument variation. Zero observed branching. Estimated current cost: ~$87/mo (23 sessions × ~$3.80 average) → This looks like a deployment script, not an agent task. Suggested: replace with `scripts/deploy-staging.sh`. Estimated savings: $87/mo, plus ~30s latency per execution.
Find planning your agent keeps redoing and pays for every time.
Repeated planning detected (last 30d): • Cluster "patch-release": 31 sessions share one plan skeleton (read changelog → bump version → run tests → tag → push) • Planning portion: ~2,100 tokens/session on claude-opus-4-7 • The skeleton is identical across all 31 runs; only the version string and date change. • You paid to generate this plan 31 times. • Estimated recoverable: ~$54/mo if served from a plan cache (or ~$61/mo if converted to a slash command)
Right-size the subagents hiding your session spend.
Subagent right-sizing (last 30d, claude-code): 147 subagents across 12 sessions ran in this window. Subagent spend: $284.10 (66% of window cost). • researcher-3 opus, 1.2K out, 3 tools [over_powered] • summarizer-1 opus, 61K ctx in [over_provisioned] Flagged spend to review: $52.60 across 6 subagents.
Flag sessions whose output runs long for the task.
$ tj optimize verbosity Examined 247 sessions across 18 task-shape cohorts (30d)… High-verbosity candidates (top 5 of 14): • Cohort "edit_file -> run_tests": median output 620 tok • 1 session ran 1,840 out -- 2.97x the cohort median • Suggested max_tokens cap: 620 (the baseline, advisory) Estimated recoverable: ~$18/mo (soft upper bound)
See your spend, your recoverable waste, and your alerts at a glance, in a local browser dashboard.
Suggest cache_control breakpoints from repeated prompt prefixes.
$ tj optimize cache-recommend Anthropic prompts only. Scanning captured prefixes (last 30d)... Breakpoint candidates: 2 stable prefixes, 3+ occurrences each • Prefix seen in 34 calls, ~640 tokens ("You are a code review...") • Prefix seen in 11 calls, ~310 tokens ("<system>You have acce...") → Each candidate ships a ready cache_control snippet to paste inEstimated recoverable: ~$9/mo (read rate minus one write per prefix)
Flag prompt files worth summarizing without losing structure.
$ tj optimize summarize Scanning CLAUDE.md, .claude/rules, .claude/skills, .claude/commands... Summarize candidates: 2 files worth compressing • CLAUDE.md: 4,213 tokens, loads every turn -> ~1,850 after rewrite • .claude/skills/deploy/SKILL.md: 2,900 tokens, invoked 14x in 30d → Diff-reviewed rewrite; code blocks and tables verified byte-for-byteEstimated recoverable: ~$16/mo across always-loaded + on-demand reads
Catch context your agent already sent, sent again.
$ tj optimize resend Comparing prompt size per turn across 247 sessions (last 30d)... Repeat context: turns re-sending tokens already sent earlier • Token-weighted repeat share: 58% (conservative lower bound) • Largest offenders: long sessions with a growing tool-output tail → Fix: offload the context-heavy work to a subagent, then right-size itEstimated recoverable: ~$38/mo from the in-scope offload lever
Spot MCP servers and always-on context you never use.
$ tj optimize deadweight Checking configured MCP servers against session tool-call logs... Dead weight: 1 configured server, zero invocations across 5+ sessions • `notion` (user-scoped): present in 9 sessions, 0 notion__* calls → Review before removing; a low-traffic server can still be load-bearing → Fix: claude mcp remove notionEstimated recoverable: ~$7/mo in avoided schema-injection tax
Surface blockers your agents keep silently re-hitting.
$ tj optimize relearn Clustering repeated failures across sessions (last 30d)... Relearn: 1 blocker re-hit in 3+ sessions, never written down • "Edit before Read" on generated files: 6 sessions, 14 occurrences • Same tool error, same fix, every time; nobody wrote the rule down → Proposed fix: a CLAUDE.md rule (review before it writes)Already cost: $6.20 in re-read tokens across those 6 sessions
All twelve are in the open-source CLI. Install once, analyze everything.
Benchmark & Evaluate · the Prove beat
A downsize candidate is a hypothesis. Bench runs the cheaper model against the original on real task suites and reports, per suite, whether accuracy holds. Pass rate with Wilson confidence intervals and a McNemar p-value, a hedged verdict, never a blanket "safe".
$ tjb run --suite humaneval,gsm8k --baseline opus --candidate haiku running 200 paired tasks per suite… humaneval · 200/200 gsm8k · 200/200 humaneval REGRESSED gsm8k HOLDS verdict → ./bench-report.json
TokenJam Bench · per-suite verdict
Open source. pip install tokenjam-bench.
TokenJam Lens and TokenJam Bench bring all three — analyze, optimize, prove — into local dashboards you can explore.
Analyze
TokenJam reads from wherever your agent telemetry already lives. On Claude Code or Codex, that's your local log files. If you run Langfuse, Helicone, LangSmith, or Phoenix for observability, it ingests from there. No observability tool? It captures OpenTelemetry directly, into a local store.
Optimize
Twelve analyzers, several grounded in published research and all validated against your own data, surface cheaper-model, prompt-trimming, and re-send candidates with explicit confidence levels. TokenJam never claims a smaller model would have produced an identical answer; it shows candidates with evidence and you act via tj optimize, MCP, or an exported routing config.
Evaluate · Prove
A candidate is a hypothesis, not a guarantee. TokenJam Bench runs the cheaper model against the original on real task suites and reports, per suite, whether accuracy holds: pass rate with Wilson confidence intervals and a McNemar p-value, a hedged verdict (holds or regressed). Measured, never "certified".
Also included
Everything you'd expect from a tracing tool, running locally alongside the analyzers.
Every LLM call priced as it happens. Spend per agent, model, session, and tool, visible the moment it occurs.
Full span tree per session. See exactly which tools ran, in what order, and how long each step took.
13 alert types, 6 channels (ntfy, Discord, Telegram, webhook, file, stdout). Get pinged before damage is done.
Z-score baselines flag when your agent starts behaving differently. No LLM-on-LLM evaluation required.
Declare a JSON Schema for your tools or let TokenJam infer one. Violations are caught the instant they occur.
tj serve runs a dashboard at 127.0.0.1:7391. Prometheus metrics at /metrics. No cloud, no signup.
Three commands. Local. No signup.
Open source · MIT · runs 100% locally · no signup