# Claude Code & Codex

Monitor every Claude Code and Codex session with two commands. No SDK, no code changes.

---

TokenJam ships first-class support for the two most-used coding agents: **Claude Code** and **OpenAI Codex**. Both work with zero code changes. `tj` listens on the OTel telemetry the agent already emits, out-of-band, with no MCP server in the loop.

## Claude Code

Monitor every Claude Code session (costs, tool calls, API requests, errors) with two commands:

```bash
pipx install tokenjam
tj init --claude-code
# Restart Claude Code, then:
tj status --agent claude-code-<project>
```

`tj init --claude-code` does everything in one shot (`tj onboard` is registered as an alias of the same command):

- Creates a shared config at `~/.config/tj/config.toml` (one config for all projects).
- Writes OTLP exporter vars to `~/.claude/settings.json`.
- Wires a zero-token statusline (`tj statusline`) into `~/.claude/settings.json` — it shows this session's re-read share and nudges `/compact` before re-reading eats your quota.
- Wires a `SessionStart` hook (`tj resume-brief --from-hook`) that re-injects your prior session's method as context after a resume or post-compaction restart.
- Installs a background daemon (launchd on macOS, systemd on Linux).
- Installs a `claude` shell wrapper so each terminal renders as its own dashboard tile.
- Adds Docker harness-compatible OTLP env vars to `~/.zshrc`.
- Backfills your existing Claude Code session history so the dashboard isn't empty on first run.

**`tj init --claude-code` does not register an MCP server.** An earlier version ran `claude mcp add --scope user tj -- tj mcp`, but a measured A/B showed an in-loop MCP server costs Claude Code subscription users +36% model-weighted quota against a no-tj control, mostly from tool-definition overhead paid on every turn. The statusline and resume-brief hook above are the zero-token replacement: they run outside the model's context, so they cost nothing per turn. See [MCP server](/docs/mcp-server) for where the MCP still fits (SDK / API integrations).

**Claude Code must be restarted** after running `tj init --claude-code`.

### Adding more projects

Run once per project directory:

```bash
cd /path/to/other-project
tj init --add-project   # register this repo against the existing global config
# Restart Claude Code
```

`--add-project` is the light path once setup has run anywhere: it registers the repo under a project namespace with no plan or budget prompt, no backfill, and no daemon restart. The project name comes from the repo folder. `tj init --claude-code` still works here and re-runs the full wizard.

Each project gets its own agent ID (`claude-code-<repo-name>`), all sharing one server and one ingest secret.

## Codex

Monitor every Codex session. Run once, globally:

```bash
pipx install tokenjam
tj init --codex
```

`tj init --codex` is project-agnostic. It writes to `~/.codex/config.toml` (Codex's single global config), so you only run it once, not once per project. Codex hardcodes `service.name="codex_exec"` in its binary, so all sessions appear under the same agent ID regardless of which repo you're working in.

`tj init --codex`:

- Writes an `[otel]` block to `~/.codex/config.toml`.
- Installs the background daemon (launchd / systemd).

Codex has no statusline or hook surface today, so unlike Claude Code it has no zero-token substitute to offer. `tj init --codex` does not register an MCP server either — the same +36% quota-tax reasoning applies, and Codex has nothing to wire the tax-free alternative into. Telemetry stays fully out-of-band: it flows in over OTel, and you read it with the `tj` CLI (`tj traces`, `tj tokenmaxx`, `tj status --agent codex_exec`).

**Codex must be restarted** after running `tj init --codex`.

```bash
tj status --agent codex_exec   # check it's working
```

## MCP server

`tj mcp` starts a stdio MCP server with 23 tools covering status, cost, alerts, traces, drift, policy suggestions, and prompt summarization. It puts tj directly in an agent's request path, which is the right fit for SDK / API integrations where tj already sits in the loop — not for Claude Code or Codex, for the quota-tax reasons above. Full tool reference: [MCP server](/docs/mcp-server).

## Uninstalling

```bash
# Remove all TokenJam data, config, daemon, and env vars:
tj uninstall --yes

# Then remove the package:
pip uninstall tokenjam -y
```

`tj uninstall` cleans up what `tj init --claude-code` writes: the daemon, `~/.config/tj/`, `~/.tj/`, the OTLP env vars and resume-brief hook in `~/.claude/settings.json`, `OTEL_RESOURCE_ATTRIBUTES` from every onboarded project's `.claude/settings.json`, and the harness env block in `~/.zshrc`. If an older onboard had registered the MCP server before the statusline became the default, `tj uninstall` deregisters that too.