# CLI reference Every user-facing tj command: setup, the cost-optimization analyzers, prompt summarization, rule and proposal writes, observability, backfill adapters, the ledger, config and ops, and the integration entrypoints. --- The `tj` CLI is the primary interface to TokenJam. `--json` is a global flag, and the query commands honour it for machine-readable output. Commands that query alerts exit with code 1 when active (unacknowledged) alerts exist. ## Quick reference | Command | What it does | Group | |---|---|---| | `tj init` | Guided setup — config, ingest secret, daemon | Getting started | | `tj demo` | Run reproducible incident scenarios, no API keys | Getting started | | `tj ping` | Send a test span and confirm it was delivered | Getting started | | `tj upgrade` | Upgrade the package and restart the daemon | Getting started | | `tj optimize` | Run the cost-optimization analyzers | Optimize | | `tj cost` | Cost breakdown by agent, model, day, or tool | Optimize | | `tj tokenmaxx` | Shareable quota-efficiency card | Optimize | | `tj context` | Where your quota goes — re-read vs net-new work | Optimize | | `tj report` | Standalone HTML reports for analyzer findings | Optimize | | `tj route` | Write an advisory model-routing config | Optimize | | `tj rules` | Stage, apply and undo permanent CLAUDE.md rules | Optimize | | `tj relearn` | Review and apply self-improvement proposals | Optimize | | `tj summarize` | Structure-aware prompt summarization (advisory) | Prompt | | `tj status` | Current agent state — cost, tokens, alerts | Observability | | `tj traces` | Trace listing with span waterfall | Observability | | `tj trace` | Span waterfall for one trace id | Observability | | `tj alerts` | Alert history with filters | Observability | | `tj drift` | Behavioral drift Z-scores vs baseline | Observability | | `tj tools` | Tool call counts, duration, error rates | Observability | | `tj budget` | View and set daily/session cost limits | Observability | | `tj statusline` | Print the zero-token Claude Code statusline | Observability | | `tj session-story` | Replay a Claude Code session turn-by-turn | Observability | | `tj loop` | Annotate runs and track fix outcomes | Observability | | `tj backfill` | Ingest historical telemetry from other sources | Data in | | `tj quota-audit` | Retroactive audit of Opus quota | Data in | | `tj resume-brief` | Compact brief for a resuming session | Data in | | `tj session-end` | Mark a terminal's sessions as closed | Data in | | `tj commit-note` | Write a trailered commit's session cost as a git note | Ledger | | `tj doctor` | Health check — config, DB, secret, channels | Config & ops | | `tj pricing` | Inspect the resolved model rate table | Config & ops | | `tj policy` | Preview the unified policy surface | Config & ops | | `tj serve` | Start the web UI + REST API | Config & ops | | `tj stop` | Stop the background daemon | Config & ops | | `tj reset` | Reset config and daemon, keep the package | Config & ops | | `tj uninstall` | Remove everything tj installed | Config & ops | | `tj proxy` | Manage the optional enforcement proxy | Config & ops | | `tj export` | Export spans to OTLP, JSON, CSV, openevals | Integration | | `tj mcp` | Start the MCP server (stdio) | Integration | | `tj otel-resource-attrs` | Print this project's OTel resource attributes | Integration | ## Getting started ### No-install peek There is no `tj quickstart` command. The zero-install first run is the npx / uvx entrypoint, which reads the `~/.claude/projects/*.jsonl` files already on disk into a throwaway in-memory database: ```bash npx tokenjam # or: uvx tokenjam ``` See [Quickstart](/docs/quickstart) for what it prints and [Install & upgrade](/docs/install-upgrade) for the runner requirements. ### `tj init` Guided setup. Creates the config file, generates an ingest secret, and optionally installs a background daemon. Every path prompts for your plan tier and writes it to `[budget.] plan`. `tj onboard` is registered as an alias of the same callback, so older scripts keep working. New flags are documented under `tj init`. ```bash tj init # interactive setup for any agent tj init --claude-code # zero-code Claude Code integration tj init --codex # zero-code Codex integration tj init --claude-code --plan max_5x # skip the plan prompt, set the Anthropic plan tier tj init --claude-code --reconfigure # re-prompt plan + budget against an existing config tj init --add-project # register this repo under the existing global config tj init --no-daemon # skip daemon installation tj init --analysis-span 90d # how far back tj analyzes; retention follows it tj init --backfill-days 7 # or --backfill-all for the whole history tj init --verify # poll for the first span after setup tj init --verify-only --claude-code # re-check an existing config after a restart ``` `tj init --claude-code` auto-backfills the last 30 days of your existing `~/.claude/projects/` session logs on first run, so `tj optimize`, `tj context`, and `tj tokenmaxx` work immediately. Use `--plan`, `--budget`, and `--no-daemon` together to run setup unattended (CI, Docker, a script). **Git hooks and the session-to-commit join.** ```bash tj init --hooks # prepare-commit-msg managed block in this repo tj init --notes # also the post-commit hook; implies --hooks ``` `--hooks` installs a `prepare-commit-msg` hook so a commit made from a plain shell while a Claude Code session is open carries a `TokenJam-Session` trailer, which joins it to the session at deterministic confidence. The block is managed, and a hook you already have is kept. `--notes` adds the `post-commit` hook that writes each trailered commit's session cost to `refs/notes/tokenjam`. It is off by default. **Enforcement proxy.** ```bash tj init --enforce ``` Enables the proxy in suggest mode after setup and prints what it does and does not touch. See [`tj proxy`](#tj-proxy). **Forwarding to a hosted deployment.** ```bash tj init --cloud tj_live_... --org tj init --cloud off ``` `--cloud` turns on forwarding of spans, sessions and commits with the given ingest key, paired with `--org`. The command prints what leaves the machine and asks before the first byte does; `-y` skips that confirmation. `--cloud-endpoint` points it at a non-default API base URL, and `--cloud off` turns forwarding off in place. ### `tj upgrade` Upgrade the installed package and restart the daemon in one step. Restarting matters: a running daemon keeps serving the old code until it is replaced. ```bash tj upgrade tj --version # confirm ``` ### `tj ping` Send a test span and confirm delivery. In HTTP mode it polls the daemon's read API for the span before exiting, so exit 0 means the span landed rather than that a request was attempted. ```bash tj ping tj ping --agent my-agent tj ping --json ``` ### `tj demo` Run reproducible Agent Incident Library scenarios without API keys or external services. ```bash tj demo # list available scenarios tj demo retry-loop # run one scenario tj demo retry-loop --json # machine-readable scenario output ``` ## Optimize ### `tj optimize` Runs the cost-optimization analyzers against your captured usage history. Analyzers are positional arguments — run all, or just the ones you want. ```bash tj optimize # the registry analyzers that apply to your workload tj optimize downsize # one analyzer tj optimize downsize cache reuse # several ``` **Available analyzers.** `ANALYZER_ORDER` holds fifteen names. A run covers all fifteen minus the ones that do not apply to your workload, whether or not you name them: see [when an analyzer does not run](/docs/optimize-more#when-an-analyzer-does-not-run). - `downsize` — flags sessions whose structural shape matches a cheaper-model candidate. Surfaces examples to spot-check. Never claims quality equivalence; every line says "looks like" or "candidate", never "safe to switch". - `budget-projection` — projects spend against any `[budget.] usd` ceiling you have configured. - `cache` — shows the current caching ratio per (provider, model): what share of available caching you are already getting. - `cache-recommend` — Anthropic-only structural `cache_control` placement candidates from stable prefixes in your real prompt history. - `resend` — flags context your agent already sent in an earlier turn that gets sent again. - `script` — clusters of deterministic `(tool_name, arg_shape)` sequences whose structural shape matches a plain script. Review before replacing. - `reuse` — repeated-planning clusters, surfaced as estimated recoverable tokens over the analyzed window. - `trim` — LLMLingua-2 local classifier scoring which prompt regions the model is likely to ignore. Predicted low-significance only, review before editing. Requires `[capture] prompts = true` and the `tokenjam[bloat]` extra. - `subagent` — per-subagent cost breakdown across a parent session, since folding every subagent into one parent total hides where the tokens actually went. Flags subagents worth pinning to a cheaper model via `.claude/agents/.md`. - `summarize` — reasons over the filesystem, not telemetry. Scans your prompt files (CLAUDE.md, SKILL.md, and similar) for prose worth summarizing without breaking structure. - `relearn` — surfaces blockers your agents keep silently re-hitting across sessions that never got written into a durable fix. - `verbosity` — flags (agent, model) cohorts whose output runs long relative to a baseline. The output-side lever the other analyzers miss. - `deadweight` — flags MCP servers you have configured but are not using, plus always-injected context you are paying for on every turn. - `stream-usage` — flags streaming calls that closed without reporting token usage, so you can see where the accounting has holes. - `shipped` — joins each session to the commits it produced, at a labelled confidence, and reports the measured cost of the sessions that left none or had them all reverted. `tj optimize` also accepts a sixteenth positional name, `placement`. It is not a registered analyzer: asking for it runs `downsize` and surfaces the batch-placement card from that run. For an interactive-coding-agent window the card is left out, so an absent card there is not a finding of no candidates. Every dollar figure is framed as "estimated recoverable", never a guaranteed saving. **Flags:** ```bash tj optimize --since 30d # window (default 30d) tj optimize --agent claude-code-myproj # scope to one agent tj optimize --compare last-7d # window comparison tj optimize --budget anthropic --budget-usd 50 # test a different ceiling tj optimize --export-config claude-code # write advisory routing snippet to ~/.config/tokenjam/exports/ tj optimize --export-templates # write the Reuse Markdown skeletons tj optimize --verbose # every finding card in full, not the scoreboard tj optimize --expand # render cards below the 1% significance threshold tj optimize --json # machine-readable ``` `--compare` accepts `previous`, `last-week`, `last-month`, `last-7d`, `last-30d`, or `YYYY-MM-DD:YYYY-MM-DD`. The analyzers still run against the current window only; the comparison is a window-cost diff laid beside them. **Measuring a downsize candidate instead of asserting it.** ```bash tj optimize --validate downsize tj optimize --validate downsize --samples 10 tj optimize --validate downsize -y # skip the cost-estimate confirmation ``` `--validate` re-runs the finding's candidate against the recorded baseline on a small sample of your own captured calls, using your own API key, and reports the measured token and cost delta plus a quality check. It requires `[capture] prompts = true`, and it spends real money, so an interactive run prints a cost estimate and waits for confirmation first. `-y` and `--json` both skip that prompt, so a scripted run spends without asking. `--samples` defaults to 5 and caps at 20. `downsize` is the only analyzer `--validate` accepts today. Full detail: [Validating a finding](/docs/optimize-validate). ### `tj cost` Cost breakdown by agent, model, day, or tool. Same `--compare` flag as `tj optimize` for window-over-window diffs (▲/▼ indicators, top shifts by agent and model). ```bash tj cost --since 7d tj cost --group-by model # or: agent | day | tool tj cost --compare last-7d # 7d vs prior 7d tj cost --compare last-month ``` ### `tj tokenmaxx` A shareable quota-efficiency card, built for screenshotting. It leads with the context-composition headline: what share of your quota went to overhead (re-reading history, CLAUDE.md, tool output) versus real work, then classifies you into an efficiency tier keyed on that overhead share. Lower overhead is leaner and a better tier. ```bash tj tokenmaxx # default 30-day window tj tokenmaxx --weekly # 7-day "Quota Wrapped" recap tj tokenmaxx --agent my-agent tj tokenmaxx --json ``` **Efficiency tiers** (by overhead share of quota): | Tier | Overhead share | |---|---| | 🧘 TokenMinimizer | ≤ 30% | | 🌿 LeanOperator | ≤ 50% | | ⚖️ SteadyState | ≤ 70% | | 🪨 ContextHeavy | ≤ 85% | | 🕳️ QuotaSink | > 85% | Subscription plans see a token-share headline. API plans see an "implied API value" line below it. The efficiency number is a measured token share, never a guaranteed saving. ### `tj context` Diagnose where your Claude Code quota goes: the share of tokens spent re-reading prior context (conversation history, CLAUDE.md, tool output) versus net-new work, plus recurring inclusions and `/compact` candidates. Needs a direct DB connection or a running `tj serve`. ```bash tj context tj context --since 7d --agent my-agent tj context --json ``` ### `tj report` Generate standalone HTML reports for analyzer findings. Opens in your default browser. Reuse reports also write Markdown skeleton sidecars. ```bash tj report --trim # all agents, 30d window tj report --trim my-agent # scope to one agent tj report --reuse tj report --reuse my-agent --no-open # write the file without opening ``` Output lives in `~/.cache/tokenjam/reports/`. ### `tj route` Write an advisory model-routing config from the Downsize findings. It never edits a live config in place; `--check` reports what it would write. ```bash tj route export tj route export --check ``` ### `tj rules` The staged rule-write lifecycle for permanent `CLAUDE.md` rules proposed from your own repeated blockers. Nothing is written until you apply, and every applied write can be undone per destination. ```bash tj rules list # every rule on offer, with its destination files tj rules show # the rule text, its destinations, and why tj rules stage # render one diff per destination and stage them tj rules check # re-verify staged writes against the files as they stand tj rules apply # apply staged writes (all, or one rule's) tj rules applied # applied writes that can still be undone tj rules undo # revert an applied write, per destination tj rules dismiss # stop offering a rule tj rules undismiss ``` ### `tj relearn` Review and apply the self-improvement proposals the Relearn analyzer stores. `apply` previews by default. The `cost-*` subcommands cover the cost-saving half, including advise-only fixes you apply yourself and then record. ```bash tj relearn list # stored proposals with the IDs the other subcommands take tj relearn apply # preview (default); writes only when you say so tj relearn revert # unwire if live, then restore tj relearn enable # wire an applied enforcement fix into settings.json tj relearn cost-proposals # cost-saving fixes tj relearn cost-apply tj relearn cost-mark-applied tj relearn cost-revert tj relearn eval-case # emit the eval-case JSON artifact ``` ## Prompt ### `tj summarize` Structure-aware prompt summarization (advisory). `list` scans for prompt files worth summarizing and estimates the per-call token saving (read-only). `prep` wraps a prompt's structure behind verbatim markers and emits it for a model to rewrite — `--via claude-p` or `--via api` runs the rewrite in one shot. `check` verifies a rewrite preserved every structure block (a hard gate) and stages it. `apply` writes a staged rewrite back to the file (default dry-run; `--go` writes, with a backup); `undo` restores from that backup. ```bash tj summarize list tj summarize list --recursive --json tj summarize prep path/to/prompt.md tj summarize prep path/to/prompt.md --via claude-p tj summarize check path/to/prompt.md --summary rewrite.md --prepped-hash tj summarize apply path/to/prompt.md # dry-run: prints the diff tj summarize apply --go # write the staged rewrite tj summarize undo path/to/prompt.md --go ``` ## Observability ### `tj status` Current state of every known agent — cost, tokens, tool calls, active alerts. ``` $ tj status ● my-email-agent completed (2m 14s) Cost today: $0.0340 / $5.0000 limit Tokens: 12.4k in / 3.8k out Tool calls: 47 Active session: sess-a1b2c3 send_email called (sensitive action: critical) ``` ```bash tj status tj status --agent my-agent ``` ### `tj traces` Trace listing with a span waterfall view. ```bash tj traces tj traces --since 1h ``` ### `tj trace` The full span waterfall for one trace id. ```bash tj trace tj trace --json ``` ### `tj alerts` Alert history with severity and type filters. ```bash tj alerts tj alerts --severity critical tj alerts --type sensitive_action tj alerts --since 1h tj alerts --unread # only unacknowledged alerts ``` ### `tj drift` Behavioral drift report: baseline versus latest-session Z-scores. Exit code 1 if any agent has drifted (useful for CI gating). ```bash tj drift tj drift --agent my-agent ``` ### `tj tools` Tool call summary: call counts, average duration, error rates per agent. ```bash tj tools tj tools --since 1h ``` ### `tj budget` View and set daily and session cost limits per agent. ```bash tj budget # view all budgets tj budget --agent my-agent --daily 5.00 # set daily limit tj budget --agent my-agent --session 1.00 # set session limit ``` ### `tj statusline` Print the zero-token Claude Code statusline. Claude Code invokes it out of band each turn, so it costs no model quota. `tj init --claude-code` wires it for you; this is the manual form: ```json "statusLine": { "type": "command", "command": "tj statusline" } ``` ### `tj session-story` Replay a Claude Code session turn by turn. It reconstructs the session's ordered moves, and for each delegation the subagent's mandate and what it did, from the on-disk transcript or a persisted snapshot when the transcript was pruned. ```bash tj session-story # the most recent substantial session tj session-story --session tj session-story --json ``` ### `tj loop` Annotate runs and track whether a fix held. An expectation is a run you promoted into a stored baseline; recording a rerun against it gives you a pass or regress history. ```bash tj loop annotate # leave a note, with an optional verdict tj loop annotations tj loop expect # promote a run into a stored expectation tj loop expectations tj loop record # record a rerun's outcome tj loop history ``` ## Data in ### `tj backfill` Ingest historical telemetry from local Claude Code logs or external observability exports. Idempotent — re-running the same source is safe. ```bash tj backfill claude-code # ~/.claude/projects/*.jsonl tj backfill claude-code --since 30d --quiet tj backfill langfuse --source-url https://cloud.langfuse.com --api-key tj backfill langfuse --source-file langfuse-dump.json tj backfill helicone --source-url https://api.helicone.ai --api-key tj backfill otlp --source-file traces.json # any OTLP JSON dump ``` ```bash tj backfill codex # ~/.codex/sessions/ tj backfill status # which on-disk Claude Code sessions are not yet ingested ``` Subcommands: `claude-code`, `codex`, `langfuse`, `helicone`, `otlp`, and `status`. The ingest adapters support `--since`. Claude Code also takes `--root` and `--quiet`; Langfuse and Helicone take `--source-url`, `--source-file`, and `--api-key`; OTLP takes `--source-url` and `--source-file`. ### `tj quota-audit` Retroactive audit of your Opus quota: which past Opus sessions were structurally Sonnet-shaped (small input and output, few tool calls)? Reports the percent of Opus quota reclaimable, example sessions to spot-check, and an optional tuned routing-config export. Quota-share framing, never a dollar claim. Needs a direct DB connection. ```bash tj quota-audit tj quota-audit --since 30d --agent my-agent tj quota-audit --export-config claude-code tj quota-audit --json ``` ### `tj resume-brief` Hands a resuming (or post-compaction) session a compact brief of its prior method — task, progress, dead ends, working files — instead of re-investigating. Deterministic, no LLM, zero in-loop token cost. ```bash tj resume-brief --session tj resume-brief --transcript tj resume-brief --last # most recently active session by mtime ``` ### `tj session-end` Mark a terminal's sessions as closed, so a session that a crashed or force-quit terminal left open does not read as still running. ```bash tj session-end --instance tj session-end --session ``` ## Ledger ### `tj commit-note` Attach a trailered commit's measured session cost to that commit as a git note under `refs/notes/tokenjam`. `tj init --notes` installs the `post-commit` hook that runs it for you. ```bash tj commit-note # HEAD tj commit-note ``` ## Config & ops ### `tj doctor` Health check — validates config, database connectivity, ingest secret, and alert channel reachability. ```bash tj doctor ``` Exit codes: 0 = healthy, 1 = warnings, 2 = errors. ### `tj pricing` Read-only inspection of the resolved model rate table — one row per `(provider, model)` with input, output, cache-read, and cache-write rates in USD per million tokens, plus a `source` column (`override` vs `packaged`). See [Configuration](/docs/configuration) for how to override rates locally. ```bash tj pricing list tj pricing list --model claude-opus tj pricing list --json ``` ### `tj policy` Read-only preview of the unified policy surface (alerts, capture, budget, per-agent overrides). Does not open the database. ```bash tj policy list tj policy list --json ``` ### `tj serve` Start the local REST API server with the web UI and Prometheus metrics. ```bash tj serve # foreground tj serve & # background tj serve --host 0.0.0.0 # bind to all interfaces (see the warning below) tj serve --port 8080 # custom port ``` `--host 0.0.0.0` exposes your telemetry to everyone who can reach the port. The read routes are unauthenticated by default, and `[api.auth]` does not cover it either, because the dashboard route hands its key to any requester so the page can call the API. Tunnel to a loopback listener instead: see [Sharing](/docs/web-ui#sharing). Web UI: `http://127.0.0.1:7391/` · API docs: `http://127.0.0.1:7391/docs` · Metrics: `http://127.0.0.1:7391/metrics` ### `tj stop` Stop the background daemon or a `tj serve` process, and free port 7391. ```bash tj stop ``` ### `tj reset` Reset config and daemon while keeping the package installed. This is the counterpart to `tj uninstall`, which also removes the package. Run `tj init` again to set back up. ```bash tj reset tj reset --yes # skip confirmation ``` ### `tj proxy` Manage the optional enforcement proxy. It ships in suggest mode: it records what a policy would do and enforces nothing. Traffic the gate resolves as subscription, `local` or `unknown` is forwarded unmodified and never reaches a policy decision. The mode comes from the plan tier you declared under `[budget.]`, so check that value before enabling the proxy. Full detail on [the local proxy](/docs/proxy). ```bash tj proxy status # proxy config and base-URL wiring state tj proxy enable # enable and point provider base URLs at it tj proxy killswitch # flip to pass-through-everything, listener stays up tj proxy disable # disable and remove the base-URL wiring ``` `tj init --enforce` runs `tj proxy enable` at the end of setup. ### `tj uninstall` Remove all TokenJam data, config, daemon, MCP registration, and env vars. ```bash tj uninstall # interactive confirmation tj uninstall --yes # skip confirmation ``` ## Integration ### `tj export` Export spans in multiple formats — forward to any OTel backend, or feed an evaluation pipeline. ```bash tj export --format otlp # forward to any OTel backend tj export --format json # NDJSON tj export --format csv --output spans.csv tj export --format openevals --output traces.json ``` See [Export](/docs/export) for the full reference. ### `tj mcp` Start the MCP server (stdio transport) for SDK and API integrations. `tj init --claude-code` and `--codex` do not register it — an in-loop MCP is a per-turn quota cost on subscription users. Wire it manually only if you are building an SDK or API integration: ```bash claude mcp add tj --scope user -- tj mcp ``` ```bash tj mcp ``` ### `tj otel-resource-attrs` Print this project's OTel resource attributes as a single bare line, for example `service.name=claude-code-myrepo,service.namespace=myproject`. The per-terminal `claude` shell wrapper that `tj init --claude-code` installs shells out to it and appends a `service.instance.id`, which is what makes concurrent terminals render as distinct dashboard tiles. ```bash export OTEL_RESOURCE_ATTRIBUTES="$(tj otel-resource-attrs)" ``` ## Global flags - `--json` — machine-readable output, honoured by the query commands. - `--config ` — override the config file location. - `--db ` — override the database path. - `--agent ` — scope output to a specific agent. - `--no-color` — disable colored output. - `-v` / `--verbose` — verbose logging. Per-command flags and exit codes are always in the help text: ```bash tj --help tj --help ```