tokenjam 0.6.12

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.

Claude Code plugin

TokenJam also ships as a Claude Code plugin — see plugin/ for the plugin source (plugin/.claude-plugin/plugin.json) and install instructions. It adds slash commands that wrap the tj CLI; it does not install anything on its own, so tj still needs to be on your PATH (npx tokenjam@latest or pipx install tokenjam).

/plugin marketplace add Metabuilder-Labs/tokenjam
/plugin install tokenjam@tokenjam
/tokenjam:onboard    # wires the statusline, resume-brief hook, and local telemetry ingest — same as `tj onboard --claude-code`
/tokenjam:status     # tj status
/tokenjam:optimize   # tj optimize
/tokenjam:doctor     # tj doctor
/tokenjam:uninstall  # tj uninstall --yes

The plugin deliberately does not ship its own hooks or an .mcp.json: the statusline and hooks are wired by /tokenjam:onboard calling the existing, idempotent tj onboard --claude-code, so there's exactly one writer of ~/.claude/settings.json. TokenJam's MCP server (tj mcp) also stays opt-in and out of this plugin's default install — it's built for SDK/API integrations that already sit in the request path, not for Claude Code, where an in-loop MCP measurably taxes every turn.

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.

--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.

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. A check also stays dark when its evidence does not exist on your setup; summarize reads agent instruction files off disk, which an SDK or API workload does not have, so it is not offered there. 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

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.