Optimize: the analyzers

tj optimize runs a set of analyzers over the telemetry already in your local DuckDB store. Each analyzer reads your real usage history and surfaces cost-saving candidates. You review them. You decide what to change.

tj optimize                      # run every analyzer over the last 30 days
tj optimize downsize cache       # run only the named analyzers
tj optimize --since 7d           # narrow the window

The model

Every analyzer works the same way at heart:

1. It reads spans from your DB. Nothing leaves your machine.
2. It looks for a structural pattern in that data.
3. It reports the pattern as a candidate for you to look at.

An analyzer never rewrites a prompt, never changes a model, never edits a config. The output is a list of things worth reviewing, with the evidence attached so you can spot-check before you act.

Honesty posture

This is the part that matters most, so it comes first.

An analyzer reports what it can measure. It does not claim what it cannot. A downsize candidate means “the shape of this work matches a class where a cheaper model is worth a look” — not “this would have worked on the cheaper model.” A reuse cluster reports “these plans look structurally identical” — not “these plans were interchangeable.” Every savings figure is labelled estimated recoverable, computed from a stated heuristic over the analyzed window. None of them is a promise.

You will never see “saves you,” “safe to downgrade,” “provably unchanged,” or “certified” in TokenJam output. Where an analyzer flags a candidate, it also prints the caveat that says why the flag is structural and where the limits are. Those caveats are baked into the code so they cannot be dropped by accident.

The analyzers

Analyzer	What it looks for
Downsize	Sessions whose shape matches a cheaper-model candidate
Cache	Current cache usage, plus breakpoint suggestions for Anthropic prompts
Cache Recommend	Anthropic-only cache_control breakpoint candidates from stable prefixes in your prompt history
Script	Tool sequences that repeat identically across many runs
Reuse	Sessions that re-plan the same work
Trim	Low-significance regions in captured prompts
Subagent	Per-subagent cost breakdown and right-sizing candidates
Verbosity	Agent/model cohorts whose output runs long relative to a baseline
Summarize	Prompt files worth summarizing without breaking their structure
Resend	Context your agent already sent in an earlier turn, sent again
Deadweight	Configured MCP servers and always-injected context you never actually use
Relearn	Blockers your agents keep silently re-hitting across sessions, never written into a durable fix

For the spend-facing side — where your tokens went and what you reclaimed — see Cost visibility.

Plan-tier-aware rendering

What each finding shows depends on how you pay. API users see dollar figures. Subscription users (Claude Pro / Max, ChatGPT Plus / Team / Enterprise) see token-share framing instead, because a flat monthly fee has no per-call dollar spend to reclaim. Local (Ollama) users see token counts only. When TokenJam can’t tell your plan, dollar figures are suppressed and it points you at tj onboard --reconfigure.

The rendering rules live in one place (core/framing.py) so the CLI, the REST API, and the Lens dashboard all agree.