Are you TokenMaxxing hard enough? Find out in less than a minute →

CLI reference

Every user-facing tj command — getting started, the cost-optimization analyzers, prompt summarization, observability, backfill adapters, config and ops, and integration entrypoints.

The tj CLI is the primary interface to TokenJam. Every command supports --json for machine-readable output. Commands that query alerts exit with code 1 when active (unacknowledged) alerts exist.

Quick reference

CommandWhat it doesGroup
tj quickstartZero-install first run against your Claude Code logsGetting started
tj onboardGuided setup — config, ingest secret, daemonGetting started
tj demoRun reproducible incident scenarios, no API keysGetting started
tj optimizeRun the cost-optimization analyzersOptimize
tj costCost breakdown by agent, model, day, or toolOptimize
tj tokenmaxxShareable quota-efficiency cardOptimize
tj contextWhere your quota goes — re-read vs net-new workOptimize
tj savingsTokens reclaimed by the output-trim hookOptimize
tj reportStandalone HTML reports for analyzer findingsOptimize
tj summarizeStructure-aware prompt summarization (advisory)Prompt
tj statusCurrent agent state — cost, tokens, alertsObservability
tj tracesTrace listing with span waterfallObservability
tj alertsAlert history with filtersObservability
tj driftBehavioral drift Z-scores vs baselineObservability
tj toolsTool call counts, duration, error ratesObservability
tj budgetView and set daily/session cost limitsObservability
tj backfillIngest historical telemetry from other sourcesData in
tj quota-auditRetroactive audit of Opus quotaData in
tj resume-briefCompact brief for a resuming sessionData in
tj doctorHealth check — config, DB, secret, channelsConfig & ops
tj pricingInspect the resolved model rate tableConfig & ops
tj policyPreview the unified policy surfaceConfig & ops
tj serveStart the web UI + REST APIConfig & ops
tj stopStop the background daemonConfig & ops
tj uninstallRemove everything tj installedConfig & ops
tj exportExport spans to OTLP, JSON, CSV, openevalsIntegration
tj mcpStart the MCP server (stdio)Integration

Getting started

tj quickstart

Zero-install, zero-config first run. Reads the same ~/.claude/projects/*.jsonl files ccusage does — no pip env, no config, no daemon, no on-disk database (it uses a transient in-memory backend). Shows quota composition (re-read vs net-new work) and a session timeline, then points at tj onboard to go deeper.

tj quickstart
tj quickstart --since 7d
tj quickstart --full          # lift the first-run cap (default: 300 most-recent sessions)
tj quickstart --root <path>   # override the Claude Code projects root
tj quickstart --json

tj onboard

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                                # interactive setup for any agent
tj onboard --claude-code                  # zero-code Claude Code integration
tj onboard --codex                        # zero-code Codex integration
tj onboard --claude-code --plan max_5x    # skip the plan prompt, set the Anthropic plan tier
tj onboard --claude-code --reconfigure    # re-run against an existing config
tj onboard --no-daemon                    # skip daemon installation
tj onboard --verify                       # poll for the first span after setup

tj onboard --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 onboarding unattended (CI, Docker, a script).

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                       # all analyzers
tj optimize downsize              # one analyzer
tj optimize downsize cache reuse  # several

Available analyzers:

  • 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”.
  • 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.
  • 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.
  • verbosity: flags (agent, model) cohorts whose output runs long relative to a baseline. The output-side lever the other analyzers miss.
  • summarize: reasons over the filesystem, not telemetry. Scans your prompt files (CLAUDE.md, SKILL.md, and similar) for prose worth summarizing without breaking structure.
  • resend: flags context your agent already sent in an earlier turn that gets sent again.
  • deadweight: flags MCP servers you have configured but are not using, plus always-injected context you are paying for on every turn.
  • relearn: surfaces blockers your agents keep silently re-hitting across sessions that never got written into a durable fix.
  • budget-projection — projects spend against any [budget.<provider>] usd ceiling you have configured.

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 --json                               # machine-readable

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

TierOverhead 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 savings

Show tokens reclaimed by the optional tj hook cap-output output-trim hook (estimated). Reads the append-only JSONL sink, never the database.

tj savings
tj savings --session <session_id>
tj savings --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/.

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 <trace-id>   # full span waterfall for a single trace

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

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

Subcommands: claude-code, langfuse, helicone, otlp. All 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

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
tj serve --port 8080      # custom port

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

Global flags

  • --json — machine-readable output. Every command supports this.
  • --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

Get TokenJam updates