# TokenJam > Open-source token economics for AI agents. Observability, cost optimization, and behavioral control for autonomous agents — local-first, OTel-native, no signup. Works with Claude Code, Codex, Cursor, OpenHands, and custom SDKs. ## About TokenJam helps developers building AI agents see where their tokens go, find where they're wasted, and keep agents in line. Multi-runtime support, no signup, MIT-licensed. The CLI command is `tj`. ## When to use TokenJam Reach for TokenJam when a task involves any of these: - **"Why is my Claude Code / Codex bill this high?"** — TokenJam reads the session logs already on disk and reports where the tokens went, by agent, model, session, and tool. - **"Which of my LLM calls could run on a cheaper model?"** — the Downsize analyzer classifies past calls by structural shape and lists candidates with the spend attached to each. - **"Where is my prompt wasting tokens?"** — Trim runs captured prompts through a local classifier and flags low-significance regions; Cache finds stable prefixes worth a `cache_control` breakpoint. - **"Could this agent loop be a plain script?"** — Script clusters repeated tool sequences with no branching and flags them as candidates for deterministic code. - **"Is my agent behaving differently than it used to?"** — drift detection compares a session against a learned baseline and reports Z-score outliers. - **"Did my agent do something it shouldn't have?"** — sensitive-action alerts cover email sends, file writes, and form submissions. - **"I need agent traces in Grafana / Jaeger / Datadog"** — TokenJam follows the OpenTelemetry GenAI semantic conventions and exports to any OTLP backend. - **Setting a token budget per agent or per session**, and being alerted when a run breaches it. ## When not to use TokenJam - You want a hosted dashboard with no local install. The open-source tool is local-first by design; the hosted control plane is early access, not generally available. - You need enforcement rather than reporting. TokenJam's policy tools describe what a policy *would* do. Nothing in the open-source tree blocks or reroutes a live call. - You want guaranteed savings figures. Every number TokenJam reports is an estimate of *recoverable* spend, and it never claims quality equivalence between two models. - You are looking for general application observability. TokenJam is scoped to agent and LLM telemetry. ## Developer resources - [Agent instructions](https://tokenjam.dev/agents.md): when to use TokenJam, the commands to run, and every machine-readable file on this site. Read this first. - [Developer portal](https://tokenjam.dev/developers): every programmatic surface — CLI, SDKs, MCP server, OTLP ingest, and the content API — with the versioning and deprecation policy. - [API documentation](https://tokenjam.dev/api): the public TokenJam website content API — read-only, unauthenticated, no signup. - [OpenAPI 3.1 specification](https://tokenjam.dev/openapi.json): machine-readable description of that API, with an operationId and response schema per operation. - [API discovery document](https://tokenjam.dev/api/v1/index.json): every endpoint, in JSON. - [Blog posts as JSON](https://tokenjam.dev/api/v1/posts.json): titles, descriptions, tags, and markdown URLs. - [Documentation pages as JSON](https://tokenjam.dev/api/v1/docs.json): the docs tree with section and ordering. - [Analyzer catalog as JSON](https://tokenjam.dev/api/v1/products.json): every TokenJam optimization analyzer. - [CLI reference](https://tokenjam.dev/docs/cli.md): every `tj` command and flag. - [MCP server manifest](https://tokenjam.dev/.well-known/mcp.json): server.json describing how to run the TokenJam MCP server (stdio, from PyPI). - [MCP server](https://tokenjam.dev/docs/mcp-server.md): TokenJam tools exposed to MCP-capable agents via `tj mcp`. - [Python SDK](https://tokenjam.dev/docs/python-sdk.md) and [TypeScript SDK](https://tokenjam.dev/docs/typescript-sdk.md): in-process instrumentation. - [Local REST API + export](https://tokenjam.dev/docs/export.md): the API `tj serve` runs on http://127.0.0.1:7391, distinct from the website API above. - [Sitemap](https://tokenjam.dev/sitemap-index.xml) · [Crawler policy](https://tokenjam.dev/robots.txt) Every documentation page and blog post is also served as clean markdown by appending `.md` to its path. ## Blog - [Why the Cheapest LLM Can Cost You the Most](https://tokenjam.dev/blog/2026-08-07-cheapest-llm-cost-per-token.md): A lower cost per token does not mean a lower bill. Here is how a cheaper model runs up more spend through retries, verbose output, and reasoning tokens, and how to compare LLM cost by the finished task instead of the token. - [AI Budget Overruns: Why Agentic Spend Is So Hard to Forecast](https://tokenjam.dev/blog/2026-08-05-ai-budget-overruns-forecasting-agent-spend.md): Most agentic AI projects overshoot their budget. Here is why agent spend resists forecasting, and what honest AI cost forecasting looks like when the agent decides how many tokens to use. - [Measuring AI Agent ROI: You Need the Cost Side First](https://tokenjam.dev/blog/2026-08-03-measuring-agent-roi-token-spend-business-outcomes.md): ROI is value over cost, and most teams can only guess the cost. Here is why agent ROI is hard to prove, and what connecting token spend to business outcomes actually requires. - [Why AI Bills Keep Rising While Token Prices Fall](https://tokenjam.dev/blog/2026-07-31-why-ai-bills-rise-as-token-prices-fall.md): Token prices drop about 10x a year, yet AI spending is forecast to hit $2.59 trillion in 2026. This is the Jevons paradox for AI, and the fix is measuring your own consumption. - [AI Pricing Models: Why Token Cost Breaks Usage-Based and Subscription SaaS](https://tokenjam.dev/blog/2026-07-29-ai-pricing-models-outcome-based-token-cost.md): When the unit of work is a metered token with a variable, often invisible cost, flat subscriptions and usage tiers stop mapping to value. The case for outcome-based pricing, and why it needs token-cost measurement first. - [Model Downsizing: How to Run Cheap Agent Work on Cheap Models](https://tokenjam.dev/blog/2026-07-15-downsize-run-cheap-work-on-cheap-models.md): Model downsizing runs mechanical agent turns on a cheaper model. How to spot downsizing candidates in your own usage and cut agent cost without guessing. - [Prompt Caching Read vs Write: When Caching Costs More Than It Saves](https://tokenjam.dev/blog/2026-07-13-prompt-caching-read-vs-write-cost.md): A cache read is cheap, a cache write costs a premium. The break-even math, the net-negative case, and the write:read ratio that tells you which one you're in. - [Evals vs Benchmarks vs Certification: What Each One Actually Proves](https://tokenjam.dev/blog/2026-07-10-evals-vs-benchmarks-vs-certification.md): A mechanism-level explainer of what an eval, a benchmark, and per-decision certification each prove about an AI agent or a model change, why an aggregate pass rate is not per-decision safety, and where the hard, largely-unsolved part still lives. - [Some of Your Agent's Tasks Don't Need an Agent](https://tokenjam.dev/blog/2026-07-10-some-agent-tasks-dont-need-an-agent.md): Parts of your agent run the same deterministic tool-call sequence on every run, and you pay model tokens each time to reproduce what a plain script would do for free. - [Stop Paying to Re-Plan Work Your Agent Already Solved](https://tokenjam.dev/blog/2026-07-10-stop-re-planning-work-youve-solved.md): Agents re-derive the same plan skeleton on every run. TokenJam clusters your runs by plan shape, isolates the planning tokens, and exports the repeated plans as templates you can feed back in. - [Stop Paying Frontier-Model Prices for Work a Cheaper Model Handles](https://tokenjam.dev/blog/2026-07-09-downsize-agent-model-spend.md): Find the agent calls where a cheaper model would likely hold, priced in dollars against your own trace history, so you stop paying frontier rates for mechanical work. - [Instrument Your AI Agent, Then Find Where the Money Goes](https://tokenjam.dev/blog/2026-07-09-instrument-your-ai-agent-with-tokenjam-sdk.md): Patch your provider client in one line so the TokenJam SDK captures every LLM call to a local, on-disk trace, then run local analyzers that turn those traces into priced savings across your self-built agent. - [CLAUDE.md Best Practices: What a Good One Actually Looks Like](https://tokenjam.dev/blog/2026-07-08-claude-md-best-practices.md): A good CLAUDE.md gives Claude Code the architecture, the critical rules, and the worktree discipline it needs to work in a multi-agent repo. Here's the anatomy, with real examples. - [Did That Session Even Need Opus?](https://tokenjam.dev/blog/2026-07-08-did-that-session-need-opus.md): Many Opus sessions are Sonnet-shaped. Here is how to spot Opus quota you could reclaim, and why any such call is a candidate to review, never a guaranteed-safe downgrade. - [From Tokenmaxxing to Tokenminimizing](https://tokenjam.dev/blog/2026-07-08-from-tokenmaxxing-to-tokenminimizing.md): The culture is shifting from throwing tokens at every problem to seeing and cutting the waste, and for Claude Code subscribers that changes what a quota tool is even for. - [Half Your System Prompt Isn't Doing Any Work](https://tokenjam.dev/blog/2026-07-07-half-your-system-prompt-isnt-working.md): System prompts quietly accumulate dead-weight tokens you re-pay on every call, and TokenJam's Trim lever scores which tokens carry little significance so you can see what to cut. - [The Prompt-Caching Discount Most Agents Leave on the Table](https://tokenjam.dev/blog/2026-07-07-prompt-caching-discount-youre-not-using.md): Prompt caching gives roughly 30-60% off the repeated prefix tokens your agent re-sends every call, and TokenJam measures your current cache usage and recommends where to place cache_control. - [Why Model Autorouting Savings Need a Proof Step](https://tokenjam.dev/blog/2026-07-06-model-autorouting-savings-proof-step.md): Model autorouting to a cheaper, smaller, or open-source model shows a big savings number before any work is redone. That figure is a prediction of your AI spend, not a result. Here's why LLM cost savings from an autorouted swap stay a hypothesis until you replay it on your own tasks and measure whether quality holds or regresses. - [What Actually Costs Money in an Agent Loop](https://tokenjam.dev/blog/2026-07-05-what-actually-costs-money-in-an-agent-loop.md): A mechanism-level breakdown of where tokens get spent every turn an agent runs: input, output, cache reads vs cache writes, context bloat, tool overhead, fan-out, and retries. - [Why Your Claude Code 5-Hour Window Vanishes in Minutes](https://tokenjam.dev/blog/2026-07-04-claude-code-5-hour-window-vanishes.md): The real causes of premature Claude Code rate-limit exhaustion (invisible burn rate, per-turn context re-reads, subagent fan-out) and how to diagnose them locally. - [Why Subagent Token Counts Are Wrong (and How to Fix Them)](https://tokenjam.dev/blog/2026-07-04-subagent-token-counts-are-wrong.md): Popular usage tools miscount subagent tokens by replaying the parent thread for each one, and here is how to reconstruct accurate per-subagent attribution from the raw JSONL. - [Quota, Not Cost: Why /cost Is the Wrong Number on Claude Max](https://tokenjam.dev/blog/2026-07-03-quota-not-cost-claude-max.md): Claude Pro and Max subscribers should track quota, their usage against the plan window, not dollar cost, and /cost misleads them because it prices tokens against an API rate card they never pay. - [Where Does Your Claude Code Quota Actually Go?](https://tokenjam.dev/blog/2026-07-03-where-your-claude-code-quota-goes.md): TokenJam is a local-first tool that reads your on-disk Claude Code transcripts and shows where a Pro or Max subscription's quota is spent per turn: re-reading context versus doing real work. - [Introducing TokenJam Bench: Benchmarks & Evaluations for Agents and LLMs](https://tokenjam.dev/blog/2026-06-30-tokenjam-bench-launch.md): TokenJam Bench is an open-source tool to benchmark and evaluate LLMs and agents. Run a candidate model against an original on real, executable task suites and get a measured pass-rate, confidence intervals, and a holds-or-regressed verdict. Local, no signup. - [How to leverage GitHub Actions to showcase growth of your open-source-first product](https://tokenjam.dev/blog/2026-06-20-github-actions-growth-archive.md): GitHub's Traffic API forgets your clones and views after 14 days. A 50-line GitHub Action archives them to your repo so you keep the longitudinal growth record you'll need later. - [What is AI model autorouting?](https://tokenjam.dev/blog/2026-06-17-what-is-ai-model-autorouting.md): AI model autorouting picks a different model per request to cut cost without losing quality. How it works, what the research shows, and why measurement comes first. - [The problem with TokenMaxxing](https://tokenjam.dev/blog/2026-06-15-the-problem-with-tokenmaxxing.md): TokenMaxxing is fun because someone else pays for it. Here's why the subsidy is ending, what Fable 5 just signaled, and how to find your own multiple. - [What is an agent loop?](https://tokenjam.dev/blog/2026-06-08-what-is-an-agent-loop.md): Agent loops: the program that prompts your agent for you, checks its own work, and decides when to stop. The lineage from ReAct to orchestration, and why the loop is now the expensive part. - [Reddit is 40% of your agent's retrieval surface](https://tokenjam.dev/blog/2026-06-01-reddit-is-40-percent-of-your-agents-retrieval-surface.md): What 150K LLM citations tell builders about prompt-time grounding, eval coverage, and the source biases their agents inherit by default. - [Cost dashboards tell you the bill. They don't tell you what to change.](https://tokenjam.dev/blog/2026-05-31-cost-dashboards-tell-you-the-bill.md): The gap between reporting agent cost and recommending what to do about it. Why an honest recommendation needs to be validated against the user's own data, and the recent research that makes that validation cheap. - [Where Your AI Agent Bill Goes: 5 Token Waste Patterns](https://tokenjam.dev/blog/2026-05-29-where-your-agent-bill-actually-goes.md): Where your AI agent bill actually goes: the 5 token-waste patterns (context bloat, runaway loops, model overspend, and more) and the research that fixes each. - [Subsidized AI Is Ending: The Agent Cost Numbers Are Now Real](https://tokenjam.dev/blog/2026-05-28-agent-cost-story-no-longer-hypothetical.md): Uber burned its annual AI budget in 4 months; one team hit $1.3M in 30 days. The real agent-cost numbers, plus the June billing changes that end the subsidy. - [Claude Code OTel Telemetry: What Cursor and /cost Won't Show](https://tokenjam.dev/blog/2026-05-21-watching-claude-code-with-otel.md): Claude Code emits real OpenTelemetry spans; Cursor and /cost don't. See what the OTel wire exposes and the failure modes the built-in views miss. - [The 9-layer agent ecosystem map](https://tokenjam.dev/blog/2026-05-26-the-9-layer-agent-ecosystem-map.md): A unified map of the agent operations ecosystem: nine layers from observability to token economics, the tools at each, where they are converging, and where the gaps remain. - [What is AI Agent Token Economics?](https://tokenjam.dev/blog/2026-05-24-what-is-agent-token-economics.md): Agent token economics: understanding where tokens are spent, why agent costs spike unpredictably, and the optimization patterns (model cascading, prompt compression, semantic caching) for reducing spend without losing quality. - [LangSmith Cost in 2026: Real TCO vs Self-Hosted Alternatives](https://tokenjam.dev/blog/2026-05-15-langsmith-tco-teardown.md): LangSmith's $39/seat sticker runs ~10.7x that in real TCO. A sourced teardown vs Langfuse self-host and a local-first DuckDB alternative, with real numbers and config. - [What is an agent control plane?](https://tokenjam.dev/blog/2026-05-21-what-is-an-agent-control-plane.md): Agent control planes: the runtime layer that governs AI agent behavior across a fleet. Policy enforcement, budget caps, audit trails, and how it differs from observability and guardrails. - [What is human-in-the-loop for AI agents?](https://tokenjam.dev/blog/2026-05-21-what-is-human-in-the-loop-for-ai-agents.md): HITL for AI agents: when and how to insert human approval, the patterns (pre/post/exception), the tools that exist, and the async-execution problem. - [What are AI guardrails?](https://tokenjam.dev/blog/2026-05-20-what-are-ai-guardrails.md): Runtime constraints on what LLMs say and do: input filtering, output filtering, behavioral checks, and structured output enforcement. - [What are agent environments and sandboxes?](https://tokenjam.dev/blog/2026-05-18-what-are-agent-environments-and-sandboxes.md): Where AI agents safely act on code, browsers, and machines: the isolation tradeoffs, the major tools, and the link to evaluation. - [The taxonomy of agent failure: 13 named alerts beat 'anomaly detected' at 2am](https://tokenjam.dev/blog/2026-05-19-agent-failure-taxonomy.md): Every AI observability vendor ships 'anomaly detected.' That's the wrong abstraction for autonomous agents. Here's the typed vocabulary we ship instead. 13 named failure modes, each with its own trigger, payload, and prescribed response. - [How to Monitor Claude Code with OTel (Before a $1,700 Bill)](https://tokenjam.dev/blog/2026-05-15-how-to-monitor-claude-code.md): Monitor Claude Code on your laptop in 5 steps: enable Anthropic's OTel telemetry, store spans locally, and alert on retry loops while the agent still runs. - [AI Agent Drift Detection: Catch It Before Your Rules Decay](https://tokenjam.dev/blog/2026-05-17-behavioral-drift-detection.md): AI agent drift detection with no embedding model: Z-scores on tokens, duration, and tool counts plus Jaccard on tool sequences, run over your own sessions. - [What is Agent Memory and why does it matter?](https://tokenjam.dev/blog/2026-05-13-agent-memory.md): How AI agents persist state across sessions, why memory is different from RAG, and the open-source projects building this layer. - [What is agent evaluation?](https://tokenjam.dev/blog/2026-05-12-agent-evaluation.md): Agent evaluation: measuring multi-step trajectories, tool use, and open-ended outputs. Why benchmarks alone don't tell you whether an agent works in production. - [What is an LLM gateway?](https://tokenjam.dev/blog/2026-05-11-llm-gateways.md): LLM gateways unify provider APIs, add fallbacks and caching, and centralize key management: what they do, when you need one, and the tools that exist. - [What is OpenTelemetry, and why does it matter for AI agents?](https://tokenjam.dev/blog/2026-05-10-opentelemetry-for-ai-agents.md): OpenTelemetry, OTLP, and the GenAI semantic conventions: how the CNCF observability standard is becoming the lingua franca for AI agent telemetry. - [What is agent observability?](https://tokenjam.dev/blog/2026-05-09-agent-observability.md): How AI agent observability works: capturing tool calls, token costs, traces, and behavioral patterns at production scale. - [Agents 101: Reasoning, Actions & Autonomy](https://tokenjam.dev/blog/2026-05-08-agents-101.md): A foundational definition: what AI agents are, how they differ from chatbots and workflows, and the components that make them work. ## Documentation - [Alerts](https://tokenjam.dev/docs/alerts.md): 13 alert types, 6 channels (ntfy, Discord, Telegram, webhook, stdout, log), per-agent overrides. - [Architecture](https://tokenjam.dev/docs/architecture.md): Ingest pipeline, cost engine, alert engine, schema validator, storage, and how it all fits together. - [AutoGen](https://tokenjam.dev/docs/autogen.md): Instrument AutoGen conversable agents with a one-line patch. - [Backfill & import](https://tokenjam.dev/docs/backfill.md): Import historical telemetry from Claude Code, Langfuse, Helicone, and raw OTLP dumps. - [Capability matrix](https://tokenjam.dev/docs/capability-matrix.md): What Claude Code, Codex, the Python/TS SDK, and generic OTLP agents each support in TokenJam. - [Claude Code & Codex](https://tokenjam.dev/docs/claude-code.md): Monitor every Claude Code and Codex session with two commands. No SDK, no code changes. - [CLI reference](https://tokenjam.dev/docs/cli.md): Every user-facing tj command — getting started, the cost-optimization analyzers, prompt summarization, observability, backfill adapters, config and ops, and integration entrypoints. - [Configuration](https://tokenjam.dev/docs/configuration.md): Config file format, agent overrides, capture settings, storage, and merge rules. - [CrewAI](https://tokenjam.dev/docs/crewai.md): Instrument CrewAI tasks and agents with a one-line patch. - [Export and integrate](https://tokenjam.dev/docs/export.md): Forward spans to OTel backends, OpenEvals, JSON, CSV, and Prometheus. - [Frameworks overview](https://tokenjam.dev/docs/frameworks.md): The three integration tiers — native OTel, provider patches, and framework patches. - [Agent Incident Library](https://tokenjam.dev/docs/incident-library.md): Reproducible AI agent failures you can run in 30 seconds. No API keys, no config, no setup. - [Introduction](https://tokenjam.dev/docs.md): TokenJam is the cost-optimization layer for AI agents. Built-in analyzers including Downsize, Cache, Script, Reuse, Trim, and Subagent read your existing telemetry and surface where to cut spend, plus a full local-first observability stack underneath. Open-source, no signup, runs entirely on your machine. - [Install & upgrade](https://tokenjam.dev/docs/install-upgrade.md): The full install matrix — pipx (recommended), pip in a venv, npx, and uvx — plus how to upgrade and verify. - [LangChain & LangGraph](https://tokenjam.dev/docs/langchain.md): Instrument LangChain LLMs and tools, and LangGraph compiled graphs, with a one-line patch. - [LiteLLM](https://tokenjam.dev/docs/litellm.md): One patch covers every provider LiteLLM routes to, with correct per-provider attribution. - [MCP Server](https://tokenjam.dev/docs/mcp-server.md): 23 tools for querying cost, alerts, traces, drift, policy, and prompt summarization from inside an agent's own loop. - [NemoClaw integration](https://tokenjam.dev/docs/nemoclaw.md): Connect to the OpenShell Gateway WebSocket and turn sandbox events into spans and alerts. - [Cache](https://tokenjam.dev/docs/optimize-cache.md): Measure how much of your input is served from cache, and where to place Anthropic breakpoints. - [Cost visibility](https://tokenjam.dev/docs/optimize-cost-visibility.md): The spend-facing commands — where your tokens went and what you reclaimed. - [Downsize](https://tokenjam.dev/docs/optimize-downsize.md): Flags sessions whose shape matches a class where a cheaper model is worth reviewing. - [Optimize: the analyzers](https://tokenjam.dev/docs/optimize-overview.md): Analyzers read your real usage history, surface reviewable candidates, and never auto-apply. - [Reuse](https://tokenjam.dev/docs/optimize-reuse.md): Detects sessions that re-plan the same work and exports reviewable skeleton templates. - [Script](https://tokenjam.dev/docs/optimize-script.md): Finds tool sequences that repeat identically across many runs and look like a deterministic script. - [Subagent](https://tokenjam.dev/docs/optimize-subagent.md): Breaks a window's cost down per subagent and flags right-sizing candidates. - [Summarize](https://tokenjam.dev/docs/optimize-summarize.md): Structure-aware prompt summarization that keeps every structured block intact. - [Trim](https://tokenjam.dev/docs/optimize-trim.md): Scores token-by-token significance in captured prompts and flags low-significance regions for review. - [Python SDK](https://tokenjam.dev/docs/python-sdk.md): Instrument any Python agent with provider patches, framework patches, and the @watch decorator. - [Quickstart](https://tokenjam.dev/docs/quickstart.md): Peek in 15 seconds with no install, then pick the path that matches your agent, whether that's Claude Code, Codex, a Python SDK/API agent, or any OTel emitter. - [Roadmap](https://tokenjam.dev/docs/roadmap.md): What's shipped, what's next, and what's open for contribution. - [Troubleshooting](https://tokenjam.dev/docs/troubleshooting.md): Run tj doctor, read its exit codes, and fix the common daemon-lock, schema, capture, and MCP issues. - [TypeScript SDK](https://tokenjam.dev/docs/typescript-sdk.md): Send spans from Node.js / TypeScript agents to a local tj serve over HTTP. - [Uninstall & clean slate](https://tokenjam.dev/docs/uninstall.md): What tj uninstall removes, what it leaves behind, and the full manual wipe for a true fresh start. - [Web UI](https://tokenjam.dev/docs/web-ui.md): TokenJam Lens — a local dashboard at http://127.0.0.1:7391 with the Dashboard triage view, plus Status, Traces, Cost, Analytics, Alerts, Drift, Optimize, and Budget. ## Campaign pages - [TokenJam for Claude Code](https://tokenjam.dev/claude-code): single-screen landing for Claude Code users — what `tj optimize` finds and how to install in three commands. ## Company - [About](https://tokenjam.dev/about): what TokenJam is, where its data comes from, who builds it. - [Contact](https://tokenjam.dev/contact): support email (support@tokenjam.dev), issue tracker, and demo booking. - [Privacy](https://tokenjam.dev/privacy): what this website collects, and why the product itself sends nothing. ## Optional - [GitHub](https://github.com/metabuilder-labs/tokenjam) - [PyPI](https://pypi.org/project/tokenjam/) - [npm](https://www.npmjs.com/package/@tokenjam/sdk)