TokenJam reads your agent's telemetry and tells you when to downsize, when to trim prompts, what to cache, what to script, and what plans you've already paid to figure out. It then shows it all in a local browser dashboard. Runs entirely on your machine.

No cloud · No signup · No vendor lock-in

---

Get started

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.

One command sets up live capture, all thirteen analyzers, Lens (the local dashboard), and the zero-token statusline:

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

tj onboard asks how you use AI agents (Claude Code, Codex, or your own SDK/API agents) and wires the right path; under npx it first offers to make itself a permanent install. For Claude Code and Codex that means backfilling your recent history plus the statusline and hooks; restart and you're live. Then run:

tj optimize          # cost-saving candidates from your actual usage
tj serve             # open the dashboard at http://127.0.0.1:7391/

The statusline is zero-token; tj statusline runs out-of-band each turn (no model quota) and shows this session's re-read share with a /compact nudge: ◆ Opus 4.8 2.4M tok 🕳️ re-read 95% → /compact to reclaim quota. It does not add an in-loop MCP server (that's an SDK / API surface; an MCP would tax every turn).

Run bare tj any time and it points you to the next best action (tj status, tj tokenmaxx, tj optimize, or tj serve).

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

Building your own agent with the SDK: install in your project (pip install tokenjam + tj onboard); see the table below.

_{npx tokenjam and uvx tokenjam launch the Python CLI via uvx/pipx under the hood; see docs/installation.md for the runner requirements and the full install matrix.}

---

Which path are you?

pipx install tokenjam && tj onboard is the entry point for everyone: it's an interactive wizard that asks how you use AI agents and wires the right path for you. --claude-code / --codex just pre-answer the wizard's first question (skip it in scripts/CI); they're shortcuts, not separate setups.

You are	Run this	What you get
Claude Code user	tj onboard (or tj onboard --claude-code to skip the first question)	Auto-backfills your last 30 days, wires a zero-token statusline, unlocks all thirteen analyzers + Lens
Codex CLI user	tj onboard (or tj onboard --codex)	Same onboarding flow, wired for Codex's session logs
Python SDK / API agent dev	tj onboard + @watch() in your code (Python SDK)	Live capture from your own agent process, no CLI-specific backfill
Framework user (LangChain / CrewAI / AutoGen)	pip install tokenjam[langchain] (or [crewai] / [autogen]) + one patch_*() call	Framework-level spans with no manual instrumentation
Already on Langfuse / Helicone	tj backfill langfuse --source-url <url> --api-key <key> (swap langfuse → helicone, same flags)	One-time import of your existing traces into the local DB
Any OTel-emitting agent	Point your OTLP exporter at tj serve (http://127.0.0.1:7391/v1/traces)	Zero-code ingestion: no SDK, no patch

Working across multiple projects? Run tj onboard once inside each one — sessions and cost proposals group per project in Lens, keyed on the project name each onboard run captures. Already onboarded elsewhere? tj onboard --add-project registers just the current repo's namespace against your existing setup, skipping the plan/budget prompts and backfill.

LlamaIndex and the OpenAI Agents SDK ship their own native OTel support; point their exporter at tj serve rather than installing an extra. Full matrix: docs/framework-support.md.

A single page walks every path, each ending with a verify step: see docs/getting-started.md.

---

Thirteen analyzers + Lens. One install.

TokenJam reads telemetry from the major agent runtimes, frameworks, providers, and observability tools and surfaces cost-savings advisories across thirteen areas, then brings them together in a local browser dashboard.

Downsize tj optimize downsize Flags sessions where a cheaper same-family model is a downsize candidate. Never claims quality equivalence. Details →	Cache tj optimize cache Your caching ratio per (provider, model), plus suggested Anthropic prompt-cache breakpoints from your real usage. Details →
Script tj optimize script Deterministic (tool_name, arg_shape) sequences that match work a plain script could replace. Details →	Trim tj optimize trim Prompt regions the model gives little weight to. Surfaces what's safe to cut. Details →
Reuse tj optimize reuse Sessions where your agent re-plans the same work, exported as reviewable skeleton templates. Details →	Subagent right-sizing tj optimize subagent Per-subagent cost breakdown; flags premium-model or over-contexted Task calls hidden in the parent total. Details →
Verbosity tj optimize verbosity Flags sessions whose output runs long against a per-(tool, task-shape) baseline. Predicted high-verbosity output — review before constraining a response. Details →

tj optimize (no args) runs all thirteen analyzers: the seven above, plus relearn (a blocker your agent keeps silently re-hitting across sessions), budget-projection (projects your monthly run-rate against a configured [budget.<provider>] ceiling; powers Lens's Budget screen), cache-recommend (the Cache card's breakpoint-suggestion half, above), resend (token-weighted repeat-context share across turns, independent of whether caching is enabled), summarize (prompt files worth summarizing, scanned from disk), and deadweight (MCP servers whose schemas load into every session and are never called). Run a subset with tj optimize downsize cache reuse. Lens brings it all together: see the dashboard below.

---

Lens: the local dashboard

tj serve runs Lens at http://127.0.0.1:7391/: a Dashboard that lands you on recoverable waste and current health, with an embedded explorer to slice your usage any way (metric × dimension × chart); plus Status, Traces, Cost, Analytics, Alerts, Drift, Optimize, and Budget screens. Plan-tier-aware, fully offline, no signup.

→ tokenjam.dev/products/lens for the visual walkthrough.

---

Beyond optimization

TokenJam is also a full observability stack. The thirteen analyzers and Lens ride on top.

• Real-time cost tracking: every LLM call priced as it happens
• Safety alerts: 13 alert types, 6 channels (ntfy, Discord, Telegram, webhook, file, stdout)
• Behavioral drift detection: Z-score baselines, no LLM required
• Schema validation: declare or infer JSON Schema for tool outputs
• Context & quota audits: tj context (re-read vs. net-new split) and tj quota-audit (retroactive Opus usage check) over your Claude Code sessions
• Close the loop: tj loop annotates a run with a verdict, promotes a bad run into a stored expectation, and tracks whether later runs pass or regress against it
• Prompt summarization (advisory): tj summarize finds prompt files worth condensing and estimates the per-call saving
• Enforcement-plane proxy (suggest mode): tj proxy surfaces routing suggestions locally, without rewriting requests
• OTel-native: point any OTLP exporter at tj serve and you're done
• Statusline: a zero-token Claude Code status line (tj statusline, wired by tj onboard --claude-code) showing this session's re-read share + a /compact nudge
• MCP server: in-request-path tools for SDK / API users (not Claude Code / Codex subscription users, since an in-loop MCP would be a per-turn quota burden there; they get the out-of-band statusline instead)

---

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

---

Roadmap

Shipped: Downsize · Cache · Script · Trim · Reuse · Subagent right-sizing · Claude Code + Codex onboarding · MCP server · Lens web UI · Backfill adapters (Langfuse, Helicone, OTLP) · Period comparison · Routing-config export · Read-only policy preview · Context & quota audits · Close-the-loop annotations/expectations · Prompt summarization (advisory) · Enforcement-plane proxy (suggest mode)

Up next (roughly):

• Continued Lens polish + per-product visual branding
• tj policy add | edit | apply: unified rule surface (today: tj policy list / tj policy decisions)
• tj replay: replay captured sessions against new model versions
• TypeScript framework patches (LangChain JS, OpenAI Agents SDK)
• Vercel AI SDK & Mastra integrations
• Published Docker image
• GitHub Actions for CI drift/cost checks

Full version-by-version history: 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