# Quickstart

Peek in 15 seconds with no install, then pick the path that matches your agent, whether that's Claude Code, Codex, a Python SDK/API agent, or any OTel emitter.

---

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

```bash
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](/docs/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.

```bash
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](/docs/claude-code).

## Codex

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

```bash
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](/docs/claude-code).

## Python SDK / API agent

For any Python agent: Anthropic, OpenAI, Gemini, Bedrock, and [10+ frameworks](/docs/frameworks).

```bash
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.

```python
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](/docs/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.

```bash
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](/docs/install-upgrade).