Introduction

TokenJam reads your agent’s telemetry (Claude Code session logs, OTel spans, Langfuse / Helicone history) and tells you where to cut spend. The analyzers do the work. Every recommendation is structural and reviewable — nothing changes your agent automatically. It all runs locally, with no cloud, no signup, and no vendor lock-in.

The analyzers

These are the primary surface of TokenJam. Each one runs against your real usage history and emits findings you can review and act on. None of them changes your agent for you. They surface candidates, and you decide.

• 🪶 Downsize: flags sessions where a cheaper model in the same family is worth a look. It never claims quality equivalence; it surfaces example sessions so you can spot-check before switching.
• 💾 Cache: shows your current caching ratio per (provider, model), then suggests Anthropic prompt-cache breakpoints from the stable prefixes in your real usage.
• 📜 Script: clusters deterministic (tool_name, arg_shape) sequences that match the shape of work a plain script could replace, so you stop paying an LLM to re-derive the same plan.
• ♻️ Reuse: detects sessions where your agent re-plans the same work and exports reviewable skeleton templates you can drop into a slash command or script.
• ✂️ Trim: predicts which regions of your prompts the model gives little weight to and surfaces what’s safe to cut. The scoring model (LLMLingua-2) is local, so there are no API calls and no per-run cost.
• 🧩 Subagent: breaks a session’s cost down per subagent (Claude Code Task calls) and flags ones that ran on a premium model or got handed more context than the work needed.
• 🎯 Cache Recommend: identifies Anthropic cache_control breakpoint candidates from stable prefixes in your prompt history and outputs a ready-to-paste config snippet per breakpoint.
• 📏 Verbosity: flags agent/model cohorts whose output runs long relative to like-for-like baseline work, so you can review whether brevity constraints help without actually losing information.
• 📊 Budget Projection: projects your current monthly run rate against any configured provider spend ceiling, so you know your trajectory before you hit the limit.
• 📝 Summarize: finds prompt files worth condensing without breaking their structure and estimates token savings, leaving the actual edit decision with you.
• ↩️ Resend: identifies context your agent sent in an earlier turn that gets re-read by every later turn until compaction, so you can spot the repeated material.
• 🗑️ Deadweight: spots configured MCP servers and always-injected context that appear in your settings but never actually get used, so you can remove the schema-injection tax.
• 🔁 Relearn: surfaces blockers your agents keep silently re-hitting across multiple sessions instead of just once, so you can write them down and avoid the repeated re-thinking cost.
• 🌊 Stream Usage: identifies streaming calls that closed without reporting token usage due to opt-in flags or early disconnects, surfacing data-quality gaps in your observability.

tj optimize                       # all analyzers
tj optimize downsize cache reuse  # a subset (positional args)

Deep pages for each analyzer live in the Optimize section.

Running Summarize

The Summarize analyzer above has its own command interface:

tj summarize

It stages a diff-reviewed rewrite for you to review before anything touches a file. Code blocks, tables, and templates are protected verbatim, so compression never mangles the parts that have to survive byte-for-byte. Advisory only; you control the final edit.

TokenMaxx — the social entry point

tj tokenmaxx

A single-shot “how hard are you TokenMaxxing?” command. It reads your recent usage, classifies it into an efficiency tier, and surfaces your recoverable-waste figure inline. Designed as a shareable screenshot artifact.

Visit tokenjam.dev/tokenmaxxing for the tier ladder and a short quickstart.

Also included: full observability stack

The analyzers ride on top of a complete local-first observability layer. Everything below ships in the base install, so you don’t need to opt in.

Real-time cost tracking. Every LLM call is priced as it happens, by agent, model, session, and tool. Budget alerts fire before you hit the limit.

Safety alerts. Configure any tool call as a sensitive action (send_email, delete_file, submit_form) and get notified via ntfy, Discord, Telegram, webhook, or stdout.

Behavioral drift detection. tj builds a statistical baseline from your agent’s real behavior and alerts when something deviates: a prompt tweak, a model update, a dependency bump. No LLM required.

Tool output validation. Declare a JSON Schema for your tools or let tj infer one automatically. Schema violations are caught the moment they occur.

Backfill adapters. Ingest historical telemetry from Langfuse, Helicone, raw OTLP dumps, or your existing Claude Code session logs, so the analyzers have data to chew on without waiting for new runs to accumulate.

100% local. DuckDB. Local REST API. No cloud backend. No API key for TokenJam itself. Your telemetry never leaves your machine unless you explicitly export it.

Install

pipx install tokenjam

Or pick the path that matches your agent on the Quickstart. To upgrade later, see Install & upgrade.