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?

On the three agent paths the command is the same: pipx install tokenjam && tj init. tj init asks how you use AI agents and wires that answer; --claude-code and --codex pre-answer that question for scripts and CI rather than being separate setups. The OTel path below needs no answer, because nothing is being wired into your agent.

You are…	Run this	You get
A Claude Code user	`pipx install tokenjam && tj init`, answer `Claude Code` (or `tj init --claude-code`)	Backfilled history, a zero-token statusline, the analyzers that apply to a coding-agent workload, and the Lens dashboard
A Codex CLI user	`pipx install tokenjam && tj init`, answer `Codex` (or `tj init --codex`)	The same onboarding flow, wired for Codex’s session logs
A Python SDK / API agent dev	`pipx install tokenjam && tj init`, answer `Your own agents (Python/TS SDK or API)`, then `@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.

The setup command is tj init. tj onboard is registered as an alias of the same callback, so an older script keeps working. New flags are documented under tj init.

Claude Code

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

pipx install tokenjam
tj init --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 init --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 init    # asks how you use agents; pick "Your own agents (Python/TS SDK or API)"
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 init --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 cost-saving candidates, tj serve for the Lens dashboard, or tj tokenmaxx for a shareable efficiency card. To install differently or upgrade later, see Install & upgrade.