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:

npx tokenjam        # or:  uvx tokenjam

See Quickstart for what it prints and 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.<provider>] plan.

tj onboard is registered as an alias of the same callback, so older scripts keep working. New flags are documented under tj init.

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.

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.

tj init --enforce

Enables the proxy in suggest mode after setup and prints what it does and does not touch. See tj proxy.

Forwarding to a hosted deployment.

tj init --cloud tj_live_... --org <org_id>
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.

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.

tj ping
tj ping --agent my-agent
tj ping --json

`tj demo`

Run reproducible Agent Incident Library scenarios without API keys or external services.

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.

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.

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.<provider>] 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/<name>.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:

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.

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.

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

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.

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.

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.

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.

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.

tj rules list                  # every rule on offer, with its destination files
tj rules show <rule>           # the rule text, its destinations, and why
tj rules stage <rule>          # 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 <rule>           # revert an applied write, per destination
tj rules dismiss <rule>        # stop offering a rule
tj rules undismiss <rule>

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

tj relearn list                # stored proposals with the IDs the other subcommands take
tj relearn apply <id>          # preview (default); writes only when you say so
tj relearn revert <id>         # unwire if live, then restore
tj relearn enable <id>         # wire an applied enforcement fix into settings.json
tj relearn cost-proposals      # cost-saving fixes
tj relearn cost-apply <id>
tj relearn cost-mark-applied <id>
tj relearn cost-revert <id>
tj relearn eval-case <id>      # 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.

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 <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)

tj status
tj status --agent my-agent

`tj traces`

Trace listing with a span waterfall view.

tj traces
tj traces --since 1h

`tj trace`

The full span waterfall for one trace id.

tj trace <trace-id>
tj trace <trace-id> --json

`tj alerts`

Alert history with severity and type filters.

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

tj drift
tj drift --agent my-agent

`tj tools`

Tool call summary: call counts, average duration, error rates per agent.

tj tools
tj tools --since 1h

`tj budget`

View and set daily and session cost limits per agent.

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:

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

tj session-story                      # the most recent substantial session
tj session-story --session <id>
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.

tj loop annotate <session-id>      # leave a note, with an optional verdict
tj loop annotations <session-id>
tj loop expect <session-id>        # promote a run into a stored expectation
tj loop expectations
tj loop record <expectation-id>    # record a rerun's outcome
tj loop history <expectation-id>

Data in

`tj backfill`

Ingest historical telemetry from local Claude Code logs or external observability exports. Idempotent — re-running the same source is safe.

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 <key>
tj backfill langfuse --source-file langfuse-dump.json
tj backfill helicone --source-url https://api.helicone.ai --api-key <key>
tj backfill otlp --source-file traces.json                       # any OTLP JSON dump

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.

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.

tj resume-brief --session <id>
tj resume-brief --transcript <path>
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.

tj session-end --instance <service.instance.id>
tj session-end --session <session_id>

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.

tj commit-note          # HEAD
tj commit-note <sha>

Config & ops

`tj doctor`

Health check — validates config, database connectivity, ingest secret, and alert channel reachability.

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 for how to override rates locally.

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.

tj policy list
tj policy list --json

`tj serve`

Start the local REST API server with the web UI and Prometheus metrics.

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.

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.

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.

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.<provider>], so check that value before enabling the proxy. Full detail on the local proxy.

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.

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.

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 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:

claude mcp add tj --scope user -- tj mcp

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.

export OTEL_RESOURCE_ATTRIBUTES="$(tj otel-resource-attrs)"

Global flags

--json — machine-readable output, honoured by the query commands.
--config <path> — override the config file location.
--db <path> — override the database path.
--agent <id> — 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:

tj --help
tj <command> --help