tokenjam 0.6.5

TokenJam: a local-first, OTel-native cost-saving utility for AI agents

Reduce token use by up to 40%. TokenJam reads your agent's telemetry, finds overspending, and suggests fixes. Works with Claude Code, Codex, and your own SDK or API agents. Shows it all in a local browser dashboard. Runs entirely on your machine.

No cloud · No signup · No vendor lock-in

---

TokenJam ingests telemetry data about your agents from a multitude of sources and provides you a quick and easy way to visualize and optimize cost so that you get the most out of the tokens you pay for.

---

Get started

One command sets up live capture:

npx tokenjam onboard   # or: pipx install tokenjam && tj onboard

tj onboard asks how you use AI agents and wires that path: live capture, the analyzers your setup can act on, and Lens. Coding-agent users (Claude Code, Codex) also get their recent history backfilled and a zero-token status line wired in; restart the agent and you're live. SDK and API users add @watch() to their own code, or point an OTLP exporter at tj serve.

Then open the dashboard:

tj serve   # Lens, at http://127.0.0.1:7391/

It opens on your spend so far: which models, which sessions, where it went and proposed fixes. Prefer the terminal?

tj optimize          # what your usage is costing, and where it is recoverable
tj rules list        # the fixes that came out of it, and the files they'd land in

tj rules list reads the last analysis, so run it after tj optimize or after the daemon's first cycle. Not sure what to do next? Bare tj always points at the next useful command.

Just looking? npx tokenjam prints a read-only report over the logs you already have. No install, nothing kept.

---

Which path are you?

tj onboard is the entry point for everyone; the table is what it wires for each answer. Your answer also picks your analyzer set, since a coding agent and your own SDK code can change different things. Most analyzers run for both: the full split is below.

You are	Run this	What you get
Claude Code user	tj onboard	Backfills your recent history, wires a zero-token status line, unlocks the coding-agent analyzers and Lens
Codex CLI user	tj onboard	Same flow, wired for Codex's session logs
Python SDK / API dev	tj onboard, then @watch() in your code (docs)	Live capture from your own process; no CLI backfill
Framework user (LangChain / CrewAI / AutoGen)	pip install tokenjam[langchain] and one patch_*() call	Framework-level spans, no manual instrumentation
Already on Langfuse / Helicone	tj backfill langfuse --source-url <url> --api-key <key> (or helicone)	One-time import of your existing traces
Any OTel-emitting agent	Point your OTLP exporter at http://127.0.0.1:7391/v1/traces	Zero-code ingestion: no SDK, no patch

--claude-code and --codex pre-answer the wizard's first question for scripts and CI; they are shortcuts, not separate setups. Run tj onboard once inside each project you work in, since sessions and proposals group per project in Lens, or tj onboard --add-project to register another repo against a setup you already have.

LlamaIndex and the OpenAI Agents SDK ship native OTel support; point their exporter at tj serve instead of installing an extra. Full matrix: docs/framework-support.md. Every path, each ending with a verify step: docs/getting-started.md.

---

The analyzers

TokenJam reads telemetry from the major agent runtimes, frameworks, providers, and observability tools, then runs a suite of analyzers over it. They are persona-scoped: Coding agent (Claude Code, Codex), and SDK/API code. tj optimize runs everything your persona can act on; name a subset with tj optimize downsize resend relearn.

Analyzer	CC	SDK	Description
relearn	✅	✅	Blockers your agent keeps re-hitting across sessions, and what the repeated recovery costs
resend	✅	✅	How much of each turn's prompt is context you already sent, whether or not caching is on
summarize	✅	✅	Instruction files large enough to tax every session, scanned from disk
downsize	✅	✅	Sessions where a cheaper same-family model is a candidate. Never claims quality equivalence
subagent	✅	✅	Per-subagent cost hidden inside the parent session's total, and which dispatches ran over-powered
deadweight	✅	—	MCP servers whose schemas load into every session and are never called
cache	—	✅	Your caching ratio per (provider, model), and where it is worst
cache-recommend	—	✅	Where to place prompt-cache breakpoints, from the prefixes you actually repeat
trim	—	✅	Prompt regions the model gives little weight to
verbosity	—	✅	Sessions whose output runs long against a per-(tool, task-shape) baseline
script	—	✅	Deterministic tool sequences a plain script could replace
reuse	—	✅	Sessions where your agent re-plans work it has already planned

They find where your agents are overspending. They also tell you where they are not, so you don't spend a week optimizing something that was never costing you anything.

That balance is why some checks stay dark for you: when the lever that would recover a category of spend belongs to your harness rather than to you, quoting the figure only makes you feel worse. It is also why a quiet result is an answer rather than a failed scan. Optimizing has a price of its own, paid in your attention and sometimes in the agent's output, and a bill lowered by making your agent terser or dumber was never a saving.

---

Prove a swap holds: TokenJam Bench

tj optimize downsize flags candidates. It never claims the cheaper model would have produced the same answer. TokenJam Bench is the companion that checks. It runs your original and candidate models against real task suites and reports the pass-rate difference with statistics (Wilson CI + McNemar), so you get a hedged verdict ("holds" or "regressed") instead of a guess.

pip install tokenjam-bench
tjb run --original anthropic:claude-opus-4-7 --candidate anthropic:claude-haiku-4-5

Bench reports measured pass-rate on a suite, never "certified" or "quality preserved." Open source and local, like TokenJam. Learn more →

---

Documentation

Topic	Where
Getting started: every entry path, by persona	docs/getting-started.md
The first hour: what to do once data flows	docs/first-hour.md
Full CLI reference, every command and flag	docs/cli-reference.md
Downsize / Cache / Script / Trim deep-dives	docs/optimize/
Reuse analyzer deep-dive	docs/optimize/reuse.md
Prove a downsize candidate holds (TokenJam Bench)	tokenjam-bench
Claude Code & Codex integration	docs/claude-code-integration.md
Claude Code vs. Codex vs. SDK vs. OTLP: capability matrix	docs/agent-capability-matrix.md
Harness run grouping (governors / fan-out launchers)	docs/harness-integration.md
Python SDK reference	docs/python-sdk.md
TypeScript SDK reference	docs/typescript-sdk.md
Framework support (LangChain / CrewAI / etc.), including the full OTel provider/framework matrix	docs/framework-support.md
Alert channels & rule reference	docs/alerts.md
Backfill from Langfuse / Helicone / OTLP	docs/backfill/
Enforcement-plane proxy (suggest mode)	docs/proxy/overview.md
Policy rules	docs/policy/overview.md
Configuration	docs/configuration.md
Architecture deep-dive	docs/architecture.md
Installation extras (Trim, framework patches)	docs/installation.md
Export to Grafana / Datadog / NDJSON	docs/export.md
NemoClaw sandbox observer	docs/nemoclaw-integration.md
Release notes	GitHub Releases

---

Contributing

TokenJam is MIT, and contributions are welcome: from a one-line pricing fix to a whole new framework integration. A few easy on-ramps:

• Good first issues →: scoped, newcomer-friendly tasks, ready to pick up.
• Bugs: notice something off? File a bug.
• Documentation: struggled with something while getting started? Help the next person by writing or updating documentation.
• Model pricing: tokenjam/pricing/models.toml is community-maintained. Fix a rate or add a model in a single PR; no issue needed.
• Framework integrations: provider/framework patches follow one clear pattern (tokenjam/sdk/integrations/anthropic.py is the reference). Open an issue first to align on approach.
• Coding Agents are first-class citizens: TokenJam is built by Humans AND AI coding agents, and contributing with one is first-class. Claude Code: read CLAUDE.md and run /init to bring your agent up to speed. Codex / other agents: AGENTS.md has the critical rules.

Setup and the full dev workflow are in CONTRIBUTING.md.

If TokenJam saves you tokens, star it and watch for releases; we ship often.

---

tokenjam.dev · PyPI · npm · TokenJam Bench · Issues

MIT License · Built by Metabuilder Labs