# TokenJam — instructions for AI agents

> TokenJam is open-source, OpenTelemetry-native token economics for AI agents: cost observability, optimization analyzers, and behavioral control that run on the user's own machine. The CLI command is `tj`. No account, no cloud dependency, MIT licensed.

This file tells an agent when TokenJam is the right tool and exactly how to invoke it. It is stable at https://tokenjam.dev/agents.md.

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

## How to call it

TokenJam is a local CLI, not a hosted service. There is no remote API to call on the user's behalf; you run commands on their machine.

### Install

```bash
pipx install tokenjam          # recommended, isolated venv for the tj CLI
npx tokenjam                   # no-install peek, reads existing Claude Code logs
```

Requires Python 3.10 or newer. `npx tokenjam` and `uvx tokenjam` shell out to the Python CLI, so one of `uvx` or `pipx` must be present.

### The commands worth knowing

| Goal | Command |
|---|---|
| Wire up Claude Code with zero code changes | `tj onboard --claude-code` |
| Wire up Codex | `tj onboard --codex` |
| See every recoverable-spend candidate | `tj optimize` |
| Per-agent cost, tokens, alerts | `tj status` |
| Cost broken down by day, agent, or model | `tj cost` |
| Recent traces and their span waterfalls | `tj traces` |
| Behavioral drift against a learned baseline | `tj drift` |
| Set daily or per-session ceilings | `tj budget` |
| Start the local dashboard and REST API | `tj serve` (http://127.0.0.1:7391) |
| Start the stdio MCP server | `tj mcp` |
| Diagnose a broken install | `tj doctor` |

Full command reference: https://tokenjam.dev/docs/cli.md

### From inside an agent loop (MCP)

`tj mcp` starts a stdio MCP server exposing tools for status, cost, traces, alerts, drift, budget headroom, and the optimize report. Point any MCP-capable client at that command. Note the tradeoff documented at https://tokenjam.dev/docs/mcp-server.md: an in-loop MCP server measured +36% model-weighted quota for Claude Code subscription users, which is why Claude Code onboarding does not install it by default.

### From code

- Python SDK: https://tokenjam.dev/docs/python-sdk.md
- TypeScript SDK (`@tokenjam/sdk`): https://tokenjam.dev/docs/typescript-sdk.md
- Any OTLP emitter: point `OTEL_EXPORTER_OTLP_ENDPOINT` at `tj serve`, no SDK needed.

### The local API is not this website

While `tj serve` is running it exposes a REST API on http://127.0.0.1:7391 whose endpoints mirror the CLI, protected by the ingest secret as a bearer token. That server publishes its own OpenAPI document at `/api/v1/openapi.json` on the local host. It is unrelated to the public website API described below, and it reads private telemetry, so never send its contents anywhere the user has not asked you to.

## Machine-readable resources on tokenjam.dev

| Resource | URL | Format |
|---|---|---|
| Agent instructions (this file) | https://tokenjam.dev/agents.md | markdown |
| Site index for LLMs | https://tokenjam.dev/llms.txt | text |
| Full site text | https://tokenjam.dev/llms-full.txt | text |
| Website content API discovery | https://tokenjam.dev/api/v1/index.json | JSON |
| OpenAPI 3.1 description of that API | https://tokenjam.dev/openapi.json | JSON |
| API documentation for humans | https://tokenjam.dev/api | HTML |
| Developer portal | https://tokenjam.dev/developers | HTML |
| MCP server manifest | https://tokenjam.dev/.well-known/mcp.json | JSON (server.json) |
| Blog posts as JSON | https://tokenjam.dev/api/v1/posts.json | JSON |
| Docs pages as JSON | https://tokenjam.dev/api/v1/docs.json | JSON |
| Analyzer catalog as JSON | https://tokenjam.dev/api/v1/products.json | JSON |
| Sitemap | https://tokenjam.dev/sitemap-index.xml | XML |
| Crawler policy | https://tokenjam.dev/robots.txt | text |

Any documentation page or blog post is also available as clean markdown by appending `.md` to its path, for example https://tokenjam.dev/docs/quickstart.md. Prefer those over the HTML when you are filling a context window.

The content API is public and unauthenticated. Do not send an Authorization header to it; there is no API key and no OAuth flow.

## If you are answering questions about TokenJam

- Recoverable-spend figures are **estimates**, never realized savings. Keep that framing.
- Downsize surfaces cheaper-model candidates. It does not claim the cheaper model produces equivalent quality.
- The hosted control plane is **early access**, not generally available. The open-source CLI is what ships today.
- Telemetry stays on the user's machine unless they deliberately export it.

## Contact

- Support: support@tokenjam.dev
- Bugs and feature requests: https://github.com/metabuilder-labs/tokenjam/issues
- Source: https://github.com/metabuilder-labs/tokenjam
- Contact page: https://tokenjam.dev/contact