Token Optimizer cuts the tokens your AI coding assistant wastes, keeps your work alive across sessions and compactions, and shows you where every dollar went on a live dashboard. Most of it runs automatically. You install it, run the audit once, and the hooks do the rest.
Claude Code now lets a plugin add its own piece of interface, called a mod. Token Optimizer uses one to put your session’s health right above the prompt: a quality grade, how full the context is, how long the cache stays warm, and both usage limits. One plain sentence tells you what needs attention, and one button fixes it. Clawd, the small orange mascot, acts out what the session is doing, so you can tell at a glance whether Claude is reading, editing, waiting for your OK, or done.
Most token tools compress command output. That covers 15-25% of your context. The other 75% goes untouched.
RTK and Boost reach the first surface. Headroom reaches the first and the third. Token Optimizer covers all eight, then keeps going into what happens around compression:
These ten rows are the ones where Token Optimizer is the only 🟢 in the row: what survives beyond compression, and the waste no compressor looks for. Compression mechanics, cost and safety, and the two rows where we lose are behind the fold.
An em dash means the capability was not verified from first-party material in the 2026-07-26 source audit (Boost's first-party material re-verified 2026-08-26); it is not a claim that the capability is absent. This page scores command-output compression only; JFrog Boost's separately-shipped BoostGraph, a local code-map its agent queries on request, is a different capability and out of scope here. Boost's "pre-shell" and "shell-level" cells are sourced from its documented wrapper form (`boost
`); the mechanism `boost init` uses to wire an agent is not described in its first-party material. Token Optimizer's compression claims are tested against real sessions and an 87-fixture suite you can run yourself. **[Full benchmark methodology and results →](BENCHMARK.md)** Compaction timing now has a separate, session-grouped evaluator for advisory precision, future context need, and checkpoint/cold-resume coverage. **[Run the compaction timing evaluator →](docs/evals/README.md)**
The Dashboard
One HTML page, auto-regenerates after every session via the SessionEnd hook, no manual trigger needed. The bookmarkable URL http://localhost:24842/token-optimizer is opt-in: it only works after you run python3 skills/token-optimizer/scripts/measure.py setup-daemon to start the local server. Until then, open the file path that measure.py dashboard prints on the Dashboard: line.
Per-turn token breakdowns, cost across four pricing tiers, cache analysis with TTL mix and hit rate, quality scores overlaid on every session, subagent cost breakdown, savings tracker with metered and estimated tiers kept apart. Zero setup after install. Full dashboard docs →
What It Saves
About $597.72 in all-in API-rate-equivalent value, a priced subtotal for the 30-day snapshot ending 2026-11-01. The components keep their evidence labels:
- Logged actions: $78.59. Metered token changes across 4,945 events, valued at API rates.
- Model routing: $422.88. Estimated comparison using a frozen pre-tool mix and fixed reference model cards.
- Repeat reads avoided: $60.69. Modeled from observed turns until the next real compaction, using known per-turn rates.
- Other estimates: $35.56. All eight estimate categories are listed in the methodology, including zero-valued categories.
Pricing is incomplete. Unpriced repeat-read credits and debits are excluded; the complete net dollar value is unavailable. The four components add up to the total.
The same snapshot’s token card shows 24.80M tokens saved (9,831,072 metered + 14,966,284 estimated), about 8% of spent + saved: 286.22M spent + 24.80M saved = 311.02M. Its scope is logged tokens plus MCP caps, hint-served reads, verbosity nudges and lean resumes (snapshot taken under v5.13.63 rules; checkpoint restores have since moved to the estimated tier). Modeled repeat-read tokens and routing are outside that token-card total; the dollar subtotal has the broader scope above.
Based on 1,644 main work sessions and 3 delegated sessions. Your dashboard computes the report from your own history; results differ. Full methodology →
Active Compression
Nine features that actively reduce context, all on by default, all automatic, all toggleable from the dashboard or CLI.
Under the hood, PreToolUse hooks intercept every Read call before it enters your context. If the file was already read, only the diff comes back. If it’s a code file re-read, a structural skeleton replaces the full content. PostToolUse hooks compress CLI command output, archive the full original to disk, and log a compression event to SQLite. Nothing is lost, and everything is retrievable. You do nothing. The hooks handle it all.
| Feature |
What it does |
Savings |
| Delta Mode |
Re-reads return only what changed |
~20% on re-reads |
| Structure Map |
Unchanged file re-reads return a structural skeleton |
~30% (up to 99% per file) |
| Bash Compression |
CLI output condensed to essentials |
~10% |
| Search Compression |
grep/web results condensed to top hits + counts |
~15% |
| Lean-Output Nudges |
Steers model to concise output when context fills |
Estimated 10-15%; not counterfactually measured |
| Quality Nudges |
Warns when context quality drops |
Prevents compaction loss |
| Loop Detection |
Catches retry loops before they burn tokens |
Measured per loop |
| Activity Mode |
Adapts compaction to your session phase |
Prevents decision loss |
| Decision Extraction |
Preserves decisions across compactions |
Prevents decision drift |
Toggle from the dashboard Manage tab, CLI (measure.py v5 enable|disable <feature>), or env vars. The v5 verb is a legacy command name that controls current features.
Read how each feature works →
Per-feature details
Delta Mode
When the AI re-reads a file after editing it, the Read call returns only the diff. 65%+ of Read calls in real sessions are re-reads. A 2,000-token file re-read becomes a 50-token diff.
Disable: TOKEN_OPTIMIZER_READ_CACHE_DELTA=0
Structure Map
When Claude re-reads a code file it already saw, the Read call is blocked and replaced with a structural summary: function signatures, class hierarchies, imports. A 720KB Python file (180,000 tokens) becomes a 250-token skeleton.
Disable: TOKEN_OPTIMIZER_READ_CACHE_MODE=shadow
First-Read Skeleton
On the first read of a large code file (Python or TypeScript, 16KB–256KB) in a history-validated cohort, the Read returns a structural skeleton (signatures/imports) instead of the full file, with a one-line notice and the full content always one step away: expand <key>, a ranged Read (offset/limit), or a direct Edit. The original is archived before any substitution, fail-open — if archiving can’t happen, the full file is served.
As of v5.12, the target file is always served in full on the first read; savings come from periphery skeletons (one-hop relationships, PageRank-ordered) injected alongside the target, not from withholding the target itself. This eliminates the re-read flip-flop that demoted cohorts under the old tripwire.
This applies to code only. Markdown and other prose are not skeletoned on first read (as of v5.11.27): a headings-only outline drops load-bearing prose, so docs always come back complete. A runtime tripwire auto-demotes a code cohort back to measure-only if its live edit-rate climbs.
Disable serving (keep measurement): TOKEN_OPTIMIZER_FIRST_READ_ACTIVE=0. Disable entirely: TOKEN_OPTIMIZER_FIRST_READ_SHADOW=0. Both are also visible and toggleable via measure.py v5 status and the dashboard Manage tab.
Bash Output Compression
Rewrites common CLI commands to return compressed summaries. Covers lint, log tails, tree, docker pull, long listings, build output, and test runners. A 564-token pytest output becomes 115 tokens.
Build and test commands (gcc, cargo, npm, make, go, mvn, and more) are compressed PostToolUse even when they are not read-only: the command already ran, so the hook collapses repetition in the captured output while preserving every distinct error line, exit status, and summary. The full original is archived behind an expand pointer.
Disable: TOKEN_OPTIMIZER_BASH_COMPRESS=0
Custom Command Filters (TOML)
You can extend the bash-compression allowlist with your own read-only commands
and exclude commands you don’t want compressed, via a TOML file at
<runtime-home>/token-optimizer/command-filters.toml (override the path with
TOKEN_OPTIMIZER_COMMAND_FILTERS).
# Add a read-only command to an existing compression handler.
# handler must be one of the built-in pattern names (pytest, lint, ls, etc.).
[filters.add]
my-tests = { command = "cargo test", handler = "pytest" }
my-lint = { command = "ruff check", handler = "lint" }
# Exclude commands from compression (glob patterns supported).
[filters.exclude]
commands = ["git status", "ls -la"]
Safety is immutable: the loader rejects add entries that name a shell
interpreter (bash, python, node, …), a privilege-escalation wrapper
(sudo, su, doas), a destructive write subcommand (rm, chmod, dd,
…), or any command containing shell metacharacters (;, |, $, …).
Categorical exclusions (dangerous chars, git write subcommands, interpreters)
are enforced in the hook and dispatch code and cannot be overridden by user
config. Built-in detection always runs first, so a user add only extends
the set, never replaces a built-in handler for the same command.
Search Result Compression
When the AI runs grep, rg, or web searches that return long result lists, the output is condensed to the top hits plus a count. A 500-line grep result becomes 20 lines plus a summary.
Disable: TOKEN_OPTIMIZER_BASH_COMPRESS=0 (search compression is part of bash compression; it has no separate switch)
Lean-Output Nudges
When context fills past 25%, a short nudge tells the model to reason deeply but keep visible output lean. Fill is the only condition — quality no longer gates it, so an ordinary healthy session gets the nudge too, not just a long degraded one. The saving is estimated at 10-15%, not measured: the counterfactual (what the model would have written without the nudge) cannot be observed, so Token Optimizer reports this in the estimated tier and never folds it into metered savings. Cache-safe: injected as additionalContext, never modifies the existing prefix.
No on/off switch today (not a v5 feature). Tune the trigger point with TOKEN_OPTIMIZER_VERBOSITY_MIN_FILL (default 25).
Quality Nudges
Watches context quality in real time. When the score drops more than 15 points or crosses below 60, an inline note enters the context. Claude sees it on the next turn and surfaces the warning or adjusts behavior. Cooldown of 5 minutes, max 3 per session.
Disable: TOKEN_OPTIMIZER_QUALITY_NUDGES=0
Loop Detection
Catches the AI getting stuck on a retry loop. Compares the last 4 user messages and last 5 tool results for similarity. Fires at confidence ≥0.7, session cap of 2 notes. Savings measured from actual loop turn content.
Also catches the edit-compile-fail cycle: when the same command fails 3 times in a row with different output, a nudge suggests changing approach instead of re-running. Tunable with TOKEN_OPTIMIZER_FAIL_STREAK_THRESHOLD (default 3).
Also catches inline-script repeats: when a command with a heredoc body >= 300 chars has been run 8 times in a session, a nudge suggests saving the script to a file and running that instead, so the body is not re-sent as input tokens every turn. Tunable with TOKEN_OPTIMIZER_INLINE_SCRIPT_THRESHOLD (default 8).
Disable: TOKEN_OPTIMIZER_LOOP_DETECTION=0
UserPromptSubmit Hook
Every prompt fires the UserPromptSubmit hook, which runs the per-turn work: prompt-continuity hint, verbosity steer, quality-cache warn tick, and (in remote/container/Cowork and Codex sessions) the once-per-session ensure-health, forced cache warm, and compact-restore pointer. These six subcommands share one measure.py import inside a single dispatcher (hooks/userpromptsubmit_runner.py), so one prompt spawns three processes, not eighteen. The dispatcher uses one shared deadline (18s, 2s margin under the 20s hooks.json timeout) with fair-share budgeting across subcommands, and buffers all stdout through a single emitter for controlled, host-consumable output.
Disable the entire UserPromptSubmit path: TOKEN_OPTIMIZER_HOOKS_USERPROMPTSUBMIT=0. Checked before measure.py is imported, so the opt-out costs zero per prompt. The other hook events (PreToolUse, PostToolUse, SessionStart, Stop, etc.) are unaffected.
Activity Mode Detection
Classifies your session into one of five modes (code, debug, review, infra, general) using the last 10 tool calls. The mode feeds into compaction guidance so PRESERVE/DROP priorities adapt to what you’re doing.
Detects decision statements in real-time from tool outputs and stores them in the session database. At compaction time, these decisions are injected as CRITICAL DECISIONS that the compaction summary must preserve verbatim. Capped at 10 per session.
Measuring real savings
All compression features log to a local SQLite table. Nothing leaves your machine.
python3 measure.py compression-stats --days 30
The Session Database
Everything Token Optimizer does is backed by two local SQLite databases. Nothing leaves your machine. Zero network calls.
Per-session DB (~/.claude/token-optimizer/snapshots/session-store/<session>.db) holds 8 tables tracking file reads, tool outputs, command outputs, cached content, context intel events, activity log, decision log, and hint serves. WAL mode for concurrent read/write from hook processes. 50MB cap per session.
Trends DB (~/.claude/token-optimizer/snapshots/trends.db) holds 7 tables tracking session history, daily aggregates, skill/model/subagent usage, savings events, and compression events. Indexed by session UUID for O(log n) joins. This is what powers the dashboard, coach mode, and 30-day trend analysis.
Every compression event, every saving, every quality measurement is a row you can query. The dashboard is a read-only view of this data. measure.py compression-stats is a SQL query. Your data is your data.
Progressive Disclosure
Large tool results (>4KB) are archived to disk and replaced with a short preview plus a retrieval pointer. The full output survives compaction. When the model needs it, it pulls the original via expand, with no command re-run and no lost output.
Recovery is not compressed a second time. The optimizer’s own measure.py expand <id> command (including --session <id>) and known original-recovery tools pass through without a new archive, dedup replacement or re-fetch denial. Ordinary memory search and document retrieval keep their existing behavior.
This isn’t just storage. The system tracks how many results were archived vs re-expanded, so you can see the net tokens that stayed collapsed. Re-expansions are netted out of the savings total, so you only count what actually stayed compressed.
python3 measure.py expand --list # List archived tool results
python3 measure.py expand <tool-use-id> # Retrieve a specific result
python3 measure.py expand --search <query> # Search archived results by keyword/lineage
python3 measure.py expand <id> --lines 50:120 # Just lines 50-120 of the archive
python3 measure.py expand <id> --start 4000 --chars 2000 # A 2KB char window
python3 measure.py expand <id> --match "ERROR" --context 3 # Literal-substring context windows
--match is a literal substring (grep -F semantics), not a regex, and line
numbers count \n breaks the way grep -n/sed -n do.
expand --search runs a full-text search (FTS5 with a LIKE fallback) over
the entire archived response body — not just a prefix — plus tool name,
command, source file path, language, and archive origin. Each hit prints the
key, lineage, capture time, content hash, total length, truncation state, and
a snippet. expand <key> still returns the full stored output; the bounded
flags above return only the requested window, print a command for the next
window, and debit re-expansion savings only for the tokens actually returned.
Some MCP tools are documented to return large verbatim payloads (source fetchers, doc retrievers) where a metadata preview defeats the point. Allowlist those so their full result reaches context instead of being replaced (it’s still archived, so expand works). Set a comma-separated list of fnmatch globs matched against the full tool name:
TOKEN_OPTIMIZER_ARCHIVE_EXEMPT_TOOLS="mcp__context7__*,*github_repository_file"
Default is empty — nothing is exempt unless you opt a tool in.
Session Continuity
Compression matters, but the most important thing Token Optimizer does is keep your work alive across sessions and compactions, automatically.
When you end a session, Token Optimizer checkpoints your state to SQLite: active task, key decisions, modified files, git branch, recent reads. When you start a new session, it scores all recent checkpoints against your prompt and surfaces the most relevant one as a hint. You resume with context, not from zero.
What happens automatically:
- Cross-session hints: relevance-scored checkpoints surface when you start a new session. The hint includes the prior session’s task, decisions, files, and branch. All fenced as RECOVERED DATA, never instructions.
- Cold-resume-lean: reopen a stale session without paying the full transcript cost. Token Optimizer reconstructs a lean context from its checkpoint. No LLM call, no full-transcript cold-resume. Token-free reconstruction from SQLite.
- Hint-follow estimate: when a continuity hint surfaces file paths and the model subsequently reads one, Token Optimizer estimates an avoided exploratory search. The hint->read pair is observed; the avoided-search size is a fixed estimate, reported in the estimated tier, not the measured total.
python3 measure.py resume-lean # list reopenable cold sessions
python3 measure.py resume-lean <#|session_id> --print # emit lean context block
Compression savings only stick if your session survives compaction. Session continuity is what makes that happen.
Smart Compaction
Auto-compact rewrites the conversation into a summary. How much useful detail survives depends on the compaction and the restore, not on a fixed percentage: the paired-window event study in research/arxiv-2611.05306/ measured real sessions and found compaction count alone does not predict recovery quality. What Token Optimizer measures instead is what happens after each boundary: whether the restore was delivered, whether tool errors spike, whether the session re-reads unchanged files, repeats failed actions, or falls into loops. This release logs that evidence for calibration and shows a neutral observing status on every surface. Missing evidence stays unknown, and compaction count carries no quality penalty.
Token Optimizer checkpoints your session before compaction and restores what the summary dropped, automatically, via hooks. It also injects a context intel digest: heuristic summaries of large tool outputs the model already processed (file paths touched, errors seen, line counts). After compaction, the model knows what it saw without re-reading everything.
Activity mode detection classifies your session in real time (code, debug, review, infra, general) using the last 10 tool calls. The mode feeds into compaction guidance so PRESERVE/DROP priorities adapt to what you’re doing right now, not a generic heuristic.
Decision extraction captures decision statements from tool outputs as they happen and stores them in the session DB. At compaction time, these are injected as CRITICAL DECISIONS the summary must preserve verbatim. Capped at 10 per session.
Compression savings only stick if your session survives compaction. Saving tokens on git status doesn’t help if the next auto-compact wipes out the decision that made you run it.
How Smart Compaction works
Progressive Checkpoints
Captures session state at multiple thresholds: 20%, 35%, 50%, 65%, 80% context fill, plus quality drops below 80, 70, 50, and 40. Also snapshots before agent fan-out and after large edit batches. On restore, picks the richest eligible checkpoint.
Context Intel Digest
After compaction, Token Optimizer injects a digest of the session’s largest tool outputs: file paths touched, errors detected, line counts. Generated heuristically in <30ms, no LLM call. The model re-orients without re-reading everything.
python3 measure.py setup-smart-compact # checkpoint + restore hooks
Output Tokens: Lean vs Verbose
Output tokens are the most expensive part of your session. They cost 5x more than input tokens on Opus and are billed per generation, not per cache read. A verbose response to a simple question burns dollars you never needed to spend.
Token Optimizer handles this automatically with lean-output nudges. When your context fills past 25%, a short nudge tells the model to reason deeply but keep visible output lean. Fill is the only trigger; context quality is not a condition. The reduction is estimated at 10-15% and is not counterfactually measured, so it is reported in the estimated tier, separately from metered savings.
How it works:
- The nudge is injected as
additionalContext, never modifying the existing prefix, so your cache stays intact
- It only fires when context is filling up, not when you have plenty of room
- The model still thinks through the problem; it just produces a more concise visible answer
- No on/off switch today; tune the trigger point with
TOKEN_OPTIMIZER_VERBOSITY_MIN_FILL (default 25)
This is one of the 9 active compression features, and it’s the one that saves on the output side, where tokens cost the most.
Quality Scoring
The quality score tracks two things: Resource Health (how close you are to the degradation cliff) and Session Efficiency (whether your tokens are doing useful work). Letter grades from S to F make triage instant.
As context fills, quality drops. MRCR falls from 93% to 76% between 256K and 1M context. Your AI gets measurably dumber as the window fills. The quality score shows you exactly when that happens.
The status bar shifts color as quality degrades: green, yellow, orange, red. When quality drops below 75, session duration appears as a warning. Running subagents show with their model and elapsed time.
python3 measure.py setup-quality-bar # one-time install
Read how scoring works →
Quality score details
| Score |
Signals |
What it means |
| Resource Health |
Context fill, absolute waste tokens |
How close you are to the degradation cliff |
| Session Efficiency |
Stale reads, bloated results, decision density, agent efficiency |
Whether the session is using tokens well right now |
| Compaction recovery |
Restore delivery, post-boundary errors, re-reads, repeats, loops (matched 20-call windows) |
Whether the session actually recovered after each compaction; count alone carries no weight |
| Grade |
Range |
Meaning |
| S |
90-100 |
Peak efficiency |
| A |
80-89 |
Healthy, minor optimization possible |
| B |
70-79 |
Degradation starting |
| C |
55-69 |
Significant waste |
| D |
40-54 |
Serious problems |
| F |
0-39 |
Context is rotting, immediate action needed |
Quality bar disappeared? Running Claude Code’s /statusline overwrites Token Optimizer’s entry. SessionStart auto-restores it. Just start a new session and it’s back.
Want it off for good?
python3 measure.py setup-quality-bar --uninstall
Desktop Status Bar
Using the Claude desktop app? The status bar comes with the Token Optimizer plugin: once it is installed, the bar appears above your prompt. Nothing extra to install.
It needs Claude Code 2.1.287 or newer and Anthropic’s mods feature. Anthropic can switch mods off remotely; if that happens nothing breaks, the bar just doesn’t appear. The terminal keeps its existing status line. VS Code is not supported. To hide it, add "TOKEN_OPTIMIZER_STATUS_BAR": "0" to the env block of ~/.claude/settings.json; "TOKEN_OPTIMIZER_STATUS_BAR_ANIMATE": "0" keeps Clawd still.
- One sentence, one button: the most urgent thing about your session, with at most one button to act on it.
- Five marks: quality grade, context fill, cache countdown, 5-hour limit and weekly limit, each with its label. Hover any mark for a card with the detail.
- The arrow beside Clawd unfolds one more line: branch, session time, tool calls, compactions (when there are any), when the last checkpoint was saved (any kind, or a relevant one from an earlier session), and how many tokens Token Optimizer saved you in the last 30 days, the same total the dashboard shows. The last thing on that line is a Full dashboard link that regenerates the dashboard and opens it in your browser.
- Clawd acts out the session: thinking, reading, typing, subagents, waiting for your permission, writing, compacting, done, stopped, API error, cold cache, napping.
- Clean up: compacts with Token Optimizer’s guidance.
- Start fresh: asks for a second click, then saves a checkpoint, clears, and hands the checkpoint to your first message.
- Keep warm: a manual, one-click cache refresh. It is offered only while the cache is still warm, never runs on its own, and uses a small amount of your usage. Afterwards it tells you how many tokens it re-read from the cache.
- Two sizes: the
– button beside the arrow shrinks the band to one line (tiny Clawd, the marks, and whatever needs attention) and + brings it back. The arrow still unfolds the details row under it. The choice is remembered across sessions and restarts; TOKEN_OPTIMIZER_STATUS_BAR_SIZE=slim sets the starting size and makes the terminal status line print one line too.
Point at the bar and Clawd looks over. The cache countdown is an estimate, because Claude does not publish the exact expiry: 1 hour on Claude plans, 5 minutes on the API, measured from the session itself when possible.
Coach Mode
> /token-coach
Tell it your goal. Get back specific, prioritized fixes with exact token savings. It reads 30 days of your session data and surfaces what no single session can show: quality drifting down, sessions getting longer, cache hit rates falling, cost per session climbing.
Every insight is grounded in your actual numbers. “Your short sessions score 68 vs 60 for long ones” hits differently than “consider shorter sessions.” Coach Mode also identifies project-level optimization opportunities (skills you never use, MCP servers that load eagerly, CLAUDE.md patterns that break your cache) and teaches you how to fix them so future sessions start leaner.
Read about Coach Mode →
Coach Mode details
Historical patterns detected
| Pattern |
What it detects |
| Quality drift |
Average quality dropping week over week |
| Session duration creep |
Sessions getting longer, filling context faster |
| Cache degradation |
Cache hit rate falling (and whether model switches cause it) |
| Grade distribution |
Too many D-grade sessions piling up |
| Cost awareness |
Cost per session climbing, with routing advice |
| Duration-quality correlation |
Short sessions scoring higher, suggesting you break up long ones |
| Compression gap |
Shadow-only savings far exceeding active compression |
| Model switching |
Frequent mid-session model switches invalidating the prompt cache |
Waste detectors
11 automated detectors analyze your session patterns:
| Detector |
What it catches |
| PDF/binary ingestion |
Large files consuming context |
| Web search overhead |
Too many web results dumped into context |
| Retry churn |
Same tool retried 3+ times with errors |
| Tool cascade |
3+ consecutive tool errors |
| Looping |
Repeated similar messages |
| Overpowered model |
Opus used for simple edits |
| Weak model |
Haiku on complex tasks |
| Bad decomposition |
Monolithic 500+ word prompts |
| Wasteful thinking |
Extended thinking >2x output for small edits |
| Output waste |
Verbose responses to simple operations |
| Cache instability |
CLAUDE.md patterns that break the prompt cache |
Keep-Warm
Opt-in feature for API-billed sessions. Issues a tiny cache-read ping just before your prompt cache entry would expire, refreshing its TTL. Costs ~0.1x of the prefix versus the 1.25-2x re-write you’d pay on resume. Tripwire auto-off if pings stop paying for themselves.
python3 measure.py keepwarm-enable # opt in (API billing only)
python3 measure.py keepwarm-report # net savings, spend, tripwire state
python3 measure.py keepwarm-disable # opt out any time
Prefer a button? The desktop status bar has a manual Keep warm refresh. It is a separate one-click action, never automatic, and does not use the API-billed daemon above.
Subagent prompt cache
Claude Code only. Subagents get a 5-minute prompt cache even on a subscription, so a subagent returned to after five minutes rewrites its whole prefix. On Claude Code 2.1.243+, Token Optimizer measures whether subagentPromptCacheTtl: "1h" would pay on your own transcripts – at least 200 subagent requests in the last 30 days and an estimated saving of at least 1.15x the 1-hour write premium – and recommends it; it never sets the key for you. The recommendation carries your numbers and the exact command, in status, doctor, quick, coach, and the audit. Anyone whose subagents run once, or too rarely, gets a neutral verdict instead. The scan reads your transcripts in a background process, never inside session start. enable never overrides a value you set, never fights a CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL or FORCE_PROMPT_CACHING_5M override, and disable is final. Under the =1 opt-in (the only automatic write), a 14-day tripwire (needs at least 200 subagent requests, else “not enough data”) reverts a Token Optimizer set if your own transcripts show the 1h write premium costing more than the rewrites it avoids, counting reuse across spawns as well as within one agent.
python3 measure.py subagent-cache status # state, the verdict and why, the advice, estimated net
python3 measure.py subagent-cache enable # take the recommendation, whatever the estimate says
python3 measure.py subagent-cache disable # undo (only what Token Optimizer set; final)
TOKEN_OPTIMIZER_SUBAGENT_CACHE_1H=1 # opt in to the automatic write + tripwire
TOKEN_OPTIMIZER_SUBAGENT_CACHE_1H=0 # never: opt out permanently
Usage recommendations
Claude Code only. Once a day, Token Optimizer re-measures the two settings your own history can answer – the auto-compact window and the subagent cache lifetime – against your last 30 days and writes one usage_recommendations.json record in its own data directory. The measurement runs as a detached background process (spawned at session start or when the dashboard collects its data), never inside a hook, and a partial run retries the next day. The record shows in quick, doctor, status, coach, the audit, and the dashboard’s Coach view under “From your own usage”. When you act on a recommendation and the measured numbers move, the record says so as a “since you changed it” win – observational, never causal. Token Optimizer never writes either setting: every command it prints is one you run yourself.
python3 measure.py recommendations # the daily record: state, numbers, the exact command
python3 measure.py recommendations --json # machine-readable
python3 measure.py recommendations refresh # re-measure now (bounded; locks against a second run)
Fleet Auditor
Scans across Claude Code, Codex, and custom transcript setups to find idle burns, model misrouting, and config bloat with dollar savings per finding.
Generate model routing instructions from your actual usage data and inject them into CLAUDE.md. 48-hour staleness guard auto-removes stale advice.
python3 measure.py inject-routing --dry-run # Preview
python3 measure.py inject-routing # Inject
FAQ
🔒 Can it degrade my context quality?
No. Structural optimization only removes genuinely unused components. Active Compression controls can be disabled with a single command or env var. The quality scoring system tracks degradation in real time.
💾 Does it break the prompt cache?
No. Token Optimizer never touches content already in your context. It works on new content entering your window and on the compaction boundary. Your cache prefix stays intact, which means it saves you money twice: less input per turn, and cheaper cache reads on every turn forward.
📡 Does it send any data anywhere?
No analytics, no telemetry endpoint, no product data leaves your machine. Measurement events are local SQLite rows you own. Zero network calls.
⚠️ Can it hurt my session?
No. All hooks are non-blocking with fail-open design. If a Token Optimizer script errors, your command runs normally.
📦 Any runtime dependencies?
No. Pure Python stdlib on Claude Code and Codex. TypeScript with zero runtime deps on OpenCode and OpenClaw.
🔐 How does install.sh verify file integrity?
Resolves the latest GitHub Release tag, checks out that tag, fetches CHECKSUMS.sha256 from the same release, and verifies every script file. Out-of-band verification means a compromised commit cannot swap both code and checksums simultaneously.
All Commands
Show all commands
| Command |
What it does |
Docs |
/token-optimizer |
Full audit with 6 parallel agents, guided fixes |
→ |
/token-coach |
30-day trend analysis, prioritized fixes |
→ |
quick |
10-second health check |
→ |
doctor |
Installation check, score out of 10 |
→ |
dashboard |
Open the HTML dashboard |
→ |
savings |
Dollar savings report |
→ |
report |
Per-component token breakdown |
→ |
quality |
Context-quality analysis of live session |
→ |
trends |
Skill adoption, model mix, overhead over time |
→ |
compression-stats |
Measured savings from active compression |
→ |
memory-review |
MEMORY.md structural audit |
→ |
git-context |
Suggest files for your current diff |
→ |
drift |
Side-by-side comparison vs your last snapshot |
→ |
conversation |
Per-message token and cost breakdown |
→ |
pricing-tier |
View or switch pricing tiers |
→ |
expand |
Retrieve an archived tool result (progressive disclosure) |
→ |
resume-lean |
Reopen a cold session with token-free reconstruction |
→ |
Full CLI reference →
License
PolyForm Noncommercial 1.0.0, plus a written small business permission. Source-available.
Personal / hobby / research / education?
Go for it. Full source, runs locally, no license purchase needed. That includes your own open-source side projects. What counts is who the work is for, not where it runs: work for your employer is your employer’s use, even from home.
Small business (fewer than 5 people AND under $20k/month revenue)?
No-cost commercial license, in writing: LICENSE-SMALL-BUSINESS.md. Both limits apply to your whole company (including any parent or sister companies), not to the team or the number of people using Token Optimizer. A small team inside a larger company needs a commercial license.
Started personal, now it’s turning into a business?
Your past use is totally fine. You get 32 days after you stop qualifying to sort out a commercial license.
Larger company / commercial use?
Contact Alex Greenshpun or [email protected]. Terms are reasonable and scale with company size.
Created by Alex Greenshpun.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?v=4)
评论