Quickstart

Peek first, no install

Point TokenJam at the Claude Code session logs already on your disk. Nothing is written, no daemon runs, no config is created.

npx tokenjam        # or:  uvx tokenjam

It reads ~/.claude/projects/*.jsonl into a throwaway in-memory database and prints your quota composition and a session timeline. When you want to keep it, install the full product below and pick your path.

npx tokenjam and uvx tokenjam shell out to the Python CLI via uvx or pipx, so you need one of those runners on your machine. See Install & upgrade for the runner requirements and the full matrix.

What are you running?

You are…	Run this	You get
A Claude Code user	pipx install tokenjam && tj onboard --claude-code	Backfilled history, a zero-token statusline, all six analyzers + the Lens dashboard
A Codex CLI user	pipx install tokenjam && tj onboard --codex	The same onboarding flow, wired for Codex’s session logs
A Python SDK / API agent dev	pipx install tokenjam && tj onboard + @watch() in your code	Live capture from your own agent process
Any OTel-emitting agent	Point your OTLP exporter at tj serve	Zero-code ingestion, no SDK and no patch

Each path below ends with a verify step.

Claude Code

Two commands wire up every session (costs, tool calls, API requests, errors) with zero code changes.

pipx install tokenjam
tj onboard --claude-code
# Restart Claude Code, then verify:
tj status --agent claude-code-<project>

Onboarding creates a shared config, backfills your recent session history, installs the background daemon, and wires a zero-token statusline that shows this session’s re-read share with a /compact nudge. It does not register an MCP server — that’s an SDK/API surface, and an in-loop MCP would tax every turn.

Full guide: Claude Code & Codex.

Codex

One command, run once globally. Codex is project-agnostic, so you don’t repeat it per repo.

pipx install tokenjam
tj onboard --codex
# Restart Codex, then verify:
tj status --agent codex_exec

Codex writes to its single global config (~/.codex/config.toml), so every session lands under one agent ID. Telemetry flows in over OTel and you read it with the tj CLI.

Full guide: Claude Code & Codex.

Python SDK / API agent

For any Python agent: Anthropic, OpenAI, Gemini, Bedrock, and 10+ frameworks.

pipx install tokenjam
tj onboard    # creates config, generates the ingest secret
tj doctor     # verify your setup

Add two lines to your agent. patch_anthropic() intercepts every Anthropic call automatically, and @watch() opens a session span around your run.

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:
    # your agent code, nothing else to change
    ...

One-line patches exist for every major provider and framework. See Python SDK for the full list. Building on a framework? pip install tokenjam[langchain] (or [crewai] / [autogen]) plus one patch_*() call gives you framework-level spans.

Any OTel-compatible agent

Already emitting OpenTelemetry? Point your OTLP exporter at a running tj serve. No SDK, no patch.

tj serve &
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:7391/v1/traces
# run your agent as usual, then verify:
tj status

Many runtimes already ship OTel support out of the box.

Framework	OTel support
Claude Code	Built-in: tj onboard --claude-code
LlamaIndex	opentelemetry-instrumentation-llama-index
OpenAI Agents SDK	Built-in
Google ADK	Built-in
Strands Agent SDK (AWS)	Built-in
Pydantic AI	Built-in
Semantic Kernel	Built-in

Next steps

Once telemetry is flowing, run tj optimize for savings findings, tj serve for the Lens dashboard, or tj tokenmaxx for a shareable efficiency card. To install differently or upgrade later, see Install & upgrade.