tokenjam 0.4.1

TokenJam — local-first OTel-native observability for Autonomous AI agents

TokenJam

Token Efficiency For AI Agents

TokenJam reads your agent's telemetry and tells you when to downsize, when to trim prompts, what to cache, and what to script. The result is a lower AI bill. Runs entirely on your machine.

pipx install tokenjam

_{Don't have pipx? brew install pipx on macOS, apt install pipx on Debian/Ubuntu, or see docs/installation.md. pip install tokenjam also works in a clean venv.}

No cloud · No signup · No vendor lock-in

---

Four Analyzers. One Install.

TokenJam reads telemetry from every major agent runtime, framework, provider, and observability tool and surfaces savings across four areas.

🪶 Downsize Flags sessions where a cheaper model in the same family is worth a look. Never claims quality equivalence — surfaces examples so you can spot-check. tj optimize downsize Details →	💾 Cache Shows your current caching ratio per (provider, model) and suggests Anthropic prompt-cache breakpoints from stable prefixes in your real usage. tj optimize cache Details →
📜 Script Finds clusters of deterministic (tool_name, arg_shape) sequences that match the shape of work a plain script could replace. tj optimize script Details →	✂️ Trim Predicts which regions of your prompts the model gives little weight to. Surfaces what's safe to cut. tj optimize trim Details →

Run all four with tj optimize. Run several with tj optimize downsize cache trim.

---

30-second quickstart

For Claude Code users — zero code, auto-backfills your last 30 days:

pipx install 'tokenjam[mcp]'
tj onboard --claude-code
tj optimize          # cost-saving candidates from your actual usage

To upgrade later: pipx upgrade tokenjam (then tj stop && tj serve & to reload the daemon, and tj --version to verify). See docs/installation.md.

For any Python agent:

from tokenjam.sdk import watch
from tokenjam.sdk.integrations.anthropic import patch_anthropic

patch_anthropic()

@watch(agent_id="my-agent")
def run(task: str) -> str:
    ...

→ Python SDK · TypeScript SDK · Codex · OTel-compatible agents

---

Why local-first matters

Your spans contain prompts, completions, tool inputs, and customer data. Shipping that to a SaaS vendor for "observability" is a data-egress decision most teams aren't ready to make.

	TokenJam	LangSmith	Langfuse	Datadog LLM Obs
Signup required	❌	✅	✅	✅
Data leaves your machine	❌	✅	cloud only	✅
Cost-optimization analyzers (Downsize, Cache, Script, Trim)	✅	❌	❌	❌
Real-time sensitive-action alerts	✅	❌	❌	❌
Behavioral drift detection	✅	❌	❌	❌
OTel GenAI SemConv native	✅	partial	partial	partial
Works with any agent / framework	✅	LangChain-first	partial	❌
Free, MIT licensed	✅	freemium	freemium	paid

---

Web UI

tj serve runs a local dashboard at http://127.0.0.1:7391/ with status, traces, cost breakdown, alerts, budget, and drift.

---

Beyond optimization

TokenJam is also a full observability stack. The four analyzers 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
• OTel-native — point any OTLP exporter at tj serve and you're done
• MCP server — 14 tools letting Claude Code query its own telemetry mid-session

---

CLI

tj optimize            # all four cost-optimization analyzers
tj optimize downsize   # one analyzer
tj status              # current cost, tokens, active alerts
tj cost --since 7d     # spend by agent / model / day / tool
tj alerts              # everything that fired while you were away
tj drift               # behavioral drift Z-scores
tj backfill claude-code # ingest historical ~/.claude/projects/ sessions
tj serve               # start the web UI + REST API

Full CLI reference →

---

Documentation

Topic	Where
🪶 Downsize / Cache / Script / Trim deep-dives	docs/optimize/
Claude Code & Codex integration	docs/claude-code-integration.md
Python SDK reference	docs/python-sdk.md
TypeScript SDK reference	docs/typescript-sdk.md
Framework support (LangChain / CrewAI / etc.)	docs/framework-support.md
Alert channels & rule reference	docs/alerts.md
Backfill from Langfuse / Helicone / OTLP	docs/backfill/
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

---

Roadmap

Shipped in 0.3.x: Downsize · Cache · Script · Trim · Claude Code + Codex onboarding · MCP server · Web UI · Backfill adapters (Langfuse, Helicone, OTLP) · Period comparison · Routing-config export · Read-only policy preview

Up next:

• TokenJam Lens — local dashboard rebrand: new Overview triage front-door, Optimize detail tab, real spend-over-time charts, cross-screen drill-through
• Reuse analyzer — fifth analyzer: detects clusters of sessions with repeated planning, exports reviewable skeleton templates you can convert into slash commands or scripts
• tj policy add | edit | apply — unified rule surface
• tj replay — replay captured sessions against new model versions
• TypeScript framework patches (LangChain JS, OpenAI Agents SDK)
• Vercel AI SDK & Mastra integrations
• Docker image
• GitHub Actions for CI drift/cost checks

---

tokenjam.dev · PyPI · npm · Issues

MIT License · Built by Metabuilder Labs