CLI reference

optimAIzr docs

Find where your LLM spend is wasted, apply the savings, hold the expensive moments before they are paid, then measure what each change actually did. Everything runs on your machine: no account, no upload.

or run it once with npx optimaizr profile
  1. Step 1Install

    One global package. Node 20.11 or later, no runtime deps.

  2. Step 2Profile

    optimaizr profile reads your Claude Code, Codex and opencode sessions.

  3. Step 3Follow the lead

    It names the biggest bottleneck and the command to run next.

01Quick start

See your profile in one command

If you use Claude Code, Codex or opencode there is nothing to set up. optimAIzr reads their sessions straight from disk and answers three questions: how much you use AI, where you waste the most, and what to look at next. Once you have made a change, it opens with how that change is doing.

terminal
optimaizr profile
optimaizr profile
  Your Claude Pro did $801.89/mo of work at API prices: 40x what you pay

  Up to 30% of it can be saved: about 1.4x the work per 5-hour window and per
  week, if you take every step below.

  Where the 30% comes from
    Compact earlier                18%
    Cold cache returns              8%
    Smaller default model           3%
    6 smaller ones                  1%
    Each is taken from what the ones above leave, so nothing counts twice.

  Biggest win  Compact earlier  TEST · possible
    Up to 18% less usage (~$149.73/mo), about 1.2x the work per 5-hour window

  Where it goes
    Re-reading the conversation    41%  ████████░░░░░░░░░░░░
    Loading context into cache     34%  ███████░░░░░░░░░░░░░
    Answers, code and thinking     25%  █████░░░░░░░░░░░░░░░
    Re-reading is billed at the cache-read rate, the cheapest there is.

The maker’s own last 30 days, Sep 25 to Oct 25, 2026, with the plan detected, as a first run sees them. Once you have applied a change, the profile leaves it out of what is still to save, and opens with how it is doing. Yours come from your own usage.

02Two ways in

Agents, apps, or an export

Coding agentsNothing to change

Reads ~/.claude/projects, ~/.codex/sessions and opencode's opencode.db (opencode 1.x, on Node 22.13 or later). Anthropic and OpenAI agent spend land in one report.

Your appOne line

Wrap an Anthropic or OpenAI client. Calls keep their signature, and recording can never break a request.

app.ts
import optimaizr from "optimaizr";

const claude = optimaizr.wrap(new Anthropic(), { service: "checkout-api" });
const openai = optimaizr.wrap(new OpenAI(), { service: "checkout-api" });

Label call sites to get per-route advice:

app.ts
import { withRoute } from "optimaizr";

await withRoute("summarise-ticket", () => client.messages.create({ ... }));

Already have a usage export? Column names are matched loosely, a row's own cost is trusted over our arithmetic, and unpriceable rows are flagged, never dropped.

terminal
optimaizr import usage-export.csv --service billing
03Commands

28 commands, all free

Start here
optimaizr profile
What your plan does, the savings found and the biggest win, on one screen
optimaizr live
Every open conversation as it runs: cache countdown, warnings and fixes
optimaizr statusline on|off
Context, re-read cost and cache countdown under Claude Code's prompt
optimaizr sessions
Your costliest conversations, cold returns, and where re-reading takes over
Change things
optimaizr apply <rule>
Make the change or get its steps; alone, lists what you can change
optimaizr guard on|off
Hold a costly step once in Claude Code: an expired cache, a big read, a retry
optimaizr results [rule]
Did it work: the days after each change against the 3 to 14 days before
optimaizr undo <rule>
Take back a change optimAIzr made, or record one you stopped
optimaizr mod
The Claude Code mod: how to install it, and whether it runs
Look closer
optimaizr recommend
Ranked actions with impact and confidence
optimaizr why [path...]
Drill down: provider, model, project, workload
optimaizr show <rule>
The requests a recommendation touches
optimaizr card
Your last 30 days as an image to post, totals only
About
optimaizr privacy
What is collected, stored and sent
optimaizr feedback
Report a bug or a wrong number
optimaizr changelog
What changed in this version, offline
Other views of the same numbers
optimaizr audit
What you spend, what is recoverable, and why
optimaizr scan
The full spend report, with next steps
optimaizr tokens
Token analytics and the priciest calls
optimaizr waste
Just the opportunities
optimaizr report
Write a self-contained HTML dashboard
optimaizr metrics
How much has been analysed, and found
optimaizr limit
Record a Claude session-limit hit, so your limit is learned
For SDK and API users
optimaizr verify <rule>
Prove a fix against your quality bar
optimaizr simulate <rule>
What the change would cost, arithmetically
optimaizr import <file>
Load a CSV or JSON usage export
optimaizr guide
Which model for which job, with the arithmetic
optimaizr providers
What can be read, and from where

Flags

--why
Show every calculation and assumption
--budget N
Monthly cap in USD: the day it runs out, and what buys days back
--plan pro|max5|max20|team|team-premium
Override the Claude plan detected from Claude Code
--days N
Only the last N days
--project STR
Filter by project path
--source all|agents|sdk
Which data to read
--tz utc|local|<IANA>
Which midnight day buckets use (default UTC)
--json
Machine-readable output

live also takes --backfill N, --window N, --min-usd N, --no-prompt, --no-turns (no line after each Claude Code turn), --notify (system notifications, below) and --auto, which applies confident switches through the Claude Code mod without asking. With --json it never prompts. sessions takes --top N, how many conversations to list (10 by default). optimaizr help shows the commands you use most, and optimaizr <command> --help that command's own flags.

The cache countdown

Claude Code keeps a conversation in its cache for up to an hour. Come back after that and the next message writes all of it again, at many times what re-reading it costs. optimaizr statusline on puts a line under Claude Code's prompt, in a terminal: the conversation's size, what each message pays to re-read it, and how long its cache stays warm. In the last 15 minutes it counts down and says what coming back after will cost; once the cache has gone it says what the next message pays. Your 5-hour meter sits at the end. No mod needed, it never replaces a status line you already have, and optimaizr statusline off takes it out. The one thing it writes: when the 5-hour meter moves, the time and the new percent, to learn what 1% of your window costs.

under claude code's prompt
◉ optimAIzr · 122.7K context, $0.025/call to re-read · cache warm 55m

live counts down as well, for Claude Code, Codex and opencode, in a row for each open conversation (below), and warns 5 minutes before a long conversation's cache expires when coming back would cost 50 cents or more. The VS Code chat panel draws no status line; there the extension puts the countdown in VS Code's status bar, or run live in a terminal beside it.

Every open conversation, at a glance

live opens with a legend, not a manual: what it watches, the three marks (⚠ worth a look, ⏸ guard stepped in, ⏳ a cache about to expire), your last 7 days in a line, whether guard is on and what it kept, and the keys. On a terminal the bottom stays in place: a row for each conversation with a call in the last hour, up to four, working ones first, and the run's status line under them:

optimaizr live
  ── now ────────────────────────────────────────────────────────────────
  ⠹ Add retry logic to sync worker    Claude working · 4m 36s · $0.957 so far · 62.1K
  ○ Summarize the flaky test runs     idle 41m · 46.7K · cache warm 14m more
  ○ Review onboarding email copy      idle 45m · 41.5K · cache warm 10m more
  ○ Draft the API changelog           idle 53m · 45.6K · cache warm 2m more
  ◉ optimAIzr live · $13.24 this run · 202 calls · most: Add retry logic to sync worker $11.19 · no waste found · watching

The maker’s own run on Oct 19, 2026, 74 minutes in, with the titles changed.

A working conversation has a spinner and what the turn has cost so far; an idle one, how long its cache stays warm, in yellow for the last 15 minutes. Each conversation keeps its colour everywhere it is named. A call that came back to an expired cache says what it paid against a warm read, and whether you were away or Claude was waiting on a tool.

?
What was checked and passed: the cache hit rate, context against the compaction point, how long caches stay warm, cold returns, tool errors, models.
n
The next step for the biggest finding: what it has cost, what it still costs a call, and what to do now and next time.
a
Applies that step after a Y/N, when it is a setting optimAIzr can undo: guard, or compacting earlier.
--notify
System notifications (macOS, or notify-send on Linux) for a cache about to expire, a cold return, and a turn done after 45 seconds or more.

After each turn

When a Claude Code turn ends, one line names the conversation, then how long Claude worked, what the turn cost, its own share of your 5-hour window and the conversation so far. Over 100K a second line says what each message re-reads before anything new:

optimaizr live
  ●  1:42:43 AM  Add retry logic to sync worker    14m 21s · $3.90 · ~10% of 5h · conversation $34.15
        now 119.2K long: Claude re-reads all of it on every step, about $0.495 a message here
  ●  1:44:55 AM  Add retry logic to sync worker    11s · $0.095 · ~0.3% of 5h · conversation $34.25

The share is the turn's dollars over what 1% of your window costs, not the meter before and after: with several sessions open, all of them move it. What 1% costs is learned from the meter's history (Claude Desktop keeps one, and the status line logs a reading each time the meter moves) once three windows have each moved 5 points or more. Until then it is your plan's estimated limit over 100, and the legend says which it used. It works for conversations in the VS Code extension too. --no-turns hides it.

Your conversations

optimaizr sessions opens with your costliest conversations, by the title Claude Code gave them: what each cost with its subagents, its share of a 5-hour window, and how long Claude worked on it. Then how long your conversations run, the context size where re-reading becomes half of what a call costs, and how much of your spend went to the 1-hour cache against the 5-minute one.

Every return after the cache expired is split into the times you were away and the times Claude was waiting on a tool: a long command, a subagent or a permission prompt left open. On the 5-minute cache it names the commands that outlasted it. Each 5-hour window lists the conversations that spent it and how many ran at once, and runs started by claude -p, the SDK or codex exec are tagged headless. With guard on, conversations started from its note are measured against ones carrying on after a compaction: the first call, the wait, files read again and calls per prompt. All of it is measured from your logs.

When you answer live

Y says what it actually did. With the optimAIzr mod in Claude Code, a model swap reaches the session you are in from its next request. Without it, Y edits your settings for the next session and tells you how to undo it. When no lever exists it says so, records the decision, and hands you optimaizr verify, rather than claiming to have changed a call that was billed before it ever reached the screen.

It declines when the change is too blunt. A switch must cover at least 80% of the traffic it moves: that project, and only subagents when that is all the finding covered, with the mod; all of your Claude Code traffic without it. Below that it refuses and prints the share, because the switch would downgrade work the rule never called mechanical.

04Guard

The expensive message, held once

live says what a step cost after it was paid. Guard steps in before, through ordinary Claude Code hooks, with no mod:

terminal
optimaizr guard on        # adds its hooks to ~/.claude/settings.json
optimaizr guard off       # takes out only its own
optimaizr guard           # on or off, and what it held in the last 7 days

The first time optimaizr finds $5 or more of messages guard would have held in the last 30 days, it says how many and what they cost, and asks once to turn it on (Enter is yes). Only in a terminal: piped, with --json or in CI it never asks.

It holds each of these once, and lets it through when it comes again:

an expired cache
A message to a conversation whose cache expired, when sending it writes 50 cents or more back into the cache. It says what, as a share of your 5-hour limit on a Claude plan, and on Opus or Fable what Sonnet would pay. Not after the 5-hour limit stopped the conversation, nor for a bare “continue”.
a big read
Claude reading a whole file over 64KB. It is told to search for the part it needs or read a range, and a second whole read goes through.
a third try
The same command failing twice in a row with nothing changed in between. Claude is told to change something or say what blocks it.
/compact
Once, at the end of a turn, when the conversation is at 75% of where it compacts: compact now, before the next task starts mid-summary. Claude Code compacts under its setting (168K with 200K set, on mine), so once it has compacted 3 times under yours, the nudge goes by where it really did.
in claude code
optimAIzr held this message once. The conversation has been idle 3 days
and its cache expired, so sending it writes all 162K tokens again: about
3% of your 5-hour limit ($1.30 at API prices, Opus 5.5).
It was not sent: copy it from Original prompt below. Send it again to go
ahead, or type /clear and send it there: the new conversation starts from
a short note of where this one stood.
On Sonnet 5.5 the same rewrite is about 2% ($0.65): /model sonnet, then
send it again.

A real hold on the maker’s machine, Oct 19, 2026, in 0.12.1’s words. The note it pointed to was used, so the $1.30 was not spent. Over the last 30 days, 40 messages like it wrote their conversation into the cache again for $90.26, where a warm cache would have read it for $2.26.

A fresh start from a note. A held message isn't lost: Claude Code prints it under the hold as Original prompt. /clear in that conversation starts the new one from a short note of where the held one stood, built from its transcript with no model call:

the note
Asked last: add the retry to the webhook handler
Changed: src/webhooks.ts, test/webhooks.test.ts
Dropped: npm run e2e (failed 2 times); a change to src/queue.ts, undone
Still open: update the docs
Last reply: The handler now retries three times...

Dropped is what was tried and didn't work, so the next conversation doesn't try it again. The note goes only to the /clear of the conversation it was held in, once, within 30 minutes. optimaizr sessions measures conversations started from it against ones carrying on after a compaction.

What it kept. Every hold is logged, and so is a held step that went through after all. Only holds that stuck count: a message never sent again, a whole read never made, a retry never run. The total, as 4 catches, $2.17 not spent, shows in guard, at the start of live, on the profile, at the end of results and on the status line when there is nothing to warn about. A cold hold counts the rewrite it avoided, a big read the first write of what it would have sent; a retry has no dollar figure.

Once a week. The first turn you finish each week starts optimaizr guard week in the background, and the next turn shows its line. The same line opens live and the profile:

in claude code
optimAIzr, your last 7 days: re-reading 33% of spend (was 29%), 3 returns
to a cold cache (was 25), 1 stop at the 5-hour limit (was 1). Guard: 4
catches, $2.17 not spent.

Stops at the 5-hour limit come from Claude Code's transcripts and show when either week had one; a retry before the reset is the same stop. Guard's catches get a “was” once it has been on for a week before.

Your 5-hour pace. On a Claude plan whose limit optimAIzr has learned (from the status line's meter, Claude Desktop, or the stops Claude Code writes in its transcripts), guard works out at most every 10 minutes, in the background, whether the window runs out before it resets at the last hour's pace. From half the limit used, it says so once a window, at the end of a turn:

in claude code
optimAIzr: at the last hour's pace, your 5-hour limit runs out around
14:09, 51 minutes before it resets at 15:00. About 63% is used. Sonnet 5.5
makes it last longer: /model sonnet.

The model line shows only on a frontier model, and running out within 15 minutes of the reset isn't worth a warning. On the maker’s last 51 windows it came before all 7 stops at the limit, 19 minutes to 2h 44m ahead, 67 on the median. It also came in 10 of the 44 windows that never stopped, 4 of which still ended at 80% of the limit or more. optimaizr guard pace runs the same check by hand.

Headless runs (claude -p, the SDK) never get the weekly line, and their messages are never held. Guard reads the end of the conversation's transcript at each message and tool call, in memory: about 50ms on a 405K conversation. What it keeps is under data handling.

05Inside Claude Code

The numbers where you work

Claude Code 2.1.287 and later runs mods, plugins that work inside it. The optimAIzr mod shows what you are spending while Claude works, and lets live switch the session you are in. It is optional: the CLI, live and the status line work without it. Install it from a Claude Code session:

claude code
/plugin marketplace add blendbunjaku/optimaizr
/plugin install optimaizr@optimaizr

The spinner shows what the turn has cost so far and how full your 5-hour window is.

The band above the prompt shows the window, how long it lasts at the pace of the last hour, and when it resets. The readings come from Claude Code's own limit meter. Off a plan, it shows what the session has cost instead.

The cache countdown. Once a conversation carries 50K tokens or more, the band shows the last 15 minutes of its cache and what coming back after will cost, with one toast 5 minutes before. Past 200K it says what each request re-reads.

Handoff. /optimaizr handoff has Claude write a short note from the warm cache, for cents: what changed, what was decided, what was tried and dropped, what is open, what to check first. /clear, and the next conversation in that project starts from it. A note is used once, within 12 hours, and stays on your machine. Guard writes one with no mod and no model call when it holds a message.

Each answer gets one line: this turn $0.18 · 2m 10s · 4 requests · ~0.4% of 5h. The share is the turn's own, worked out as in live above. Set the plugin's turnLine option to false to turn it off. /optimaizr prints the session's spend, both plan windows and any switch.

The HUD. /optimaizr hud docks the session at a glance beside Claude: what the mod is doing right now (● on Sonnet 5.5, ● waiting, ● paused), what switching saved, how much cheaper it ran and roughly what share of your 5-hour window that is, spend and burn rate per hour, cache hits, both plan windows as gauges, the last turns as a sparkline, and a button (p) that pauses the switch. Toasts mark the window passing 80% and 95%, and savings passing $0.50, $1 and up.

Y switches the session you are in, when it pays. Accept a model swap in optimaizr live, or run optimaizr live --auto to apply confident ones without asking, and Claude Code uses the cheaper model from its next request, with no restart. Opus steps down to Sonnet 5.5, Sonnet to Haiku 4.5. Subagents switch at once: they start with an empty cache and hand back only a summary. A conversation already under way switches only once reloading it into the new model's cache pays back within about 10 requests; until then the band says waiting and why. After an hour idle the cache has expired, so it switches at once. If the API refuses the model, the request goes out as it was.

Going back is one command. The first switched request leaves a note in the conversation, and the band names the model you are on. For a harder task, /optimaizr off (or p in the HUD) sends that session back to its own model and /optimaizr on resumes. optimaizr undo removes the switch from every running session within seconds.

It shows what a switch saved. Each switched request is priced twice, from the token counts the API returned: at the original model's rates and at the new one's. The turn's line leads with the difference, and the band and the HUD keep a running total. Until a reload has been won back, they say so instead of showing a saving. It saves cost per token, not tokens.

Effort, and retry loops. Accepting a reasoning-effort finding lowers effort on that work from the next request, on the same model. Unlike a model switch, it keeps the cache: after /effort, low among them, the next request read the whole conversation from it in every case seen so far. And when the same command fails twice in a row with nothing changed, the mod holds the next identical attempt once and asks Claude to change something first; guard does the same without the mod.

Dollar figures are Claude Code's own total at API rates; on a plan they are not what you pay. The terminal and the Desktop app draw the spinner and the band; in the VS Code chat panel switches still apply, but nothing is drawn. optimaizr mod shows whether it is running.

06In VS Code

The countdown in VS Code's status bar

optimAIzr for VS Code reads the same history on your machine and puts it where the chat panel has no room: the status bar, a heads-up and a sidebar. Get it from the Marketplace, search optimAIzr in Extensions, or:

terminal
code --install-extension optimAIzr.optimaizr-vscode

The status bar shows the Claude Code conversation in the folder you have open: its context, the cache countdown and the 5-hour window. It turns yellow in the cache's last five minutes and red past 90% of the window. Hover for the details, click for the sidebar.

vs code's status bar
143K · 54:51 · 5h 56%

The heads-up comes about 5 minutes before a long conversation's cache expires, when coming back after it would cost $0.50 or more.

The sidebar has the savings and the fixes, biggest money first, guard's switch and what it held this week, compaction at 200K with its undo, and results. Turning guard on uses this CLI, and the extension offers to install it. A desktop alert says when a turn of 45 seconds or more finishes while VS Code is in the background, on macOS and Linux.

The status bar, the heads-up, guard and the done alert watch Claude Code; the savings also read Codex and opencode. Each alert has its own setting under optimaizr.alerts, and optimaizr.days sets the history, 7 to 90 days. VS Code 1.90 or newer. The 28-second reel is on its own page.

07The loop

From a hunch to a measured change

  1. profileWhere am I wasting the most?
  2. whyWhere does the money go?
  3. recommendWhat can I change?
  4. simulateWhat would that save?
  5. verifyWould the output still be good?
  6. applyThe change, or its steps
  7. resultsDid it work?

simulate is arithmetic on your recorded tokens and says nothing about quality. verify replays your traffic and scores it. apply never edits your code. For your app's traffic it writes the change to optimaizr-change.md for you to review, once verify passes; for a Claude Code, Codex or opencode finding it prints the steps, since the change is in how you use the agent. The one setting it does change, when you ask, is when Claude Code and Codex compact: optimaizr apply context-compaction sets it at 200K and optimaizr undo context-compaction puts back what was there.

optimaizr apply on its own lists what optimAIzr changed for you and what you can change yourself. Made one? optimaizr apply <rule> --done records when, and optimaizr undo <rule> records that you stopped. Then optimaizr results puts the days after each change against the days before:

optimaizr results
  Compact earlier: Claude Code at 200K
  applied Oct 7, 12 days ago

  Working: 5% to 24% less per prompt than the 3 to 14 days before. It
  comes with a cost: calls per prompt, tool errors per prompt,
  compactions a day, files read again after summaries a day and waiting
  for summaries a day went up.

                                                before     after
    cost per prompt                              $1.06    $0.803   -24%
    cost per call                               $0.142    $0.066   -54%
    calls per prompt                               7.5        12   +64%  trade-off
    tool errors per prompt                        0.21      0.35   +68%  trade-off
    calls past 200K                                60%        0%   -60 pts
    median context                                288K      100K   -65%
    compactions a day                             0.23       5.2   23x  trade-off
    landed mid-task                               100%       96%   -4 pts
    files read again after summaries a day        0.38       6.2   16x  trade-off
    waiting for summaries a day                   0.4m      6.8m   16x  trade-off

  Since the change: 46 conversations, 363 prompts, 68 compactions, fired
  at 168K on the median, 80 files read again after them, 0 calls past
  200K.

The maker’s own change, measured on Oct 19, 2026, 12 days in.

The verdict is judged on cost per prompt, counted only for the agent and project the change covers; under 10% either way is no clear effect. It is measured against the 3, 5, 7 and 14 days before, and when they disagree it gives the range, lowest to highest, instead of the one number that reads best. The other rows are there so a saving that costs you something shows it: more calls, more tool errors, more time waiting on summaries, and for compaction the files read again after each summary. Any of them going up is marked as a trade-off. A verdict needs 3 active days and 100 prompts after the change; until then it says how far along it is and when to look again. What it can't tell apart, such as a shift between projects or a drop already under way, it names. With guard on, it ends with what guard kept in the last 7 days. optimaizr metrics counts realised savings only from these readings.

08Reading the numbers

Every figure says what it is

measured

Provider-reported usage, priced at the rate in force. A fact.

inferred

A pattern derived from measured data by a stated rule.

estimated

A projection of how a different model or setting would behave. Could be wrong.

Confidence is about the money: how far to trust the dollar figure (low, medium or high). Impact is about the output: a saving can be arithmetically certain and still be a bad idea, which is what verify is for. Add --why to any report to see each calculation and assumption.

Three tiers, and one figure for all of them. FIX is clear waste: removing it leaves the work as it was. TRY is likely savings that change what the model does, shown as +$X. TEST is a trade-off sized from your own usage, such as compacting earlier or a smaller default model, and is only ever “up to”. Each figure also says how sure it is: high confidence, likely or possible.

The profile opens with all of them at once: “Up to 30% of it can be saved” on the maker’s run. The largest saving counts first and each one after it only on what the ones before it leave, so two changes never save the same dollar: a plain sum would have said 33%. On a plan that share is more work in each 5-hour window and each week, 1 / (1 − share): 30% less usage is about 1.4x the work. Off a plan it is dollars a month. Parts under 1% fold into one row, the rows add up to the headline, and under 5% in all the profile shows the tiers on their own lines instead.

For Claude Code, Codex and opencode the rules judge whole tasks (a prompt and every call it set off), not single calls, so normal debugging, files being written and switches that would not pay back are not counted. When two findings touch the same call, the headline counts that call once, at its largest claim.

09Budgets and plans

A cap that runs out, or a plan that stops you

A company cap. If you get a fixed amount per month, reset on the 1st, give it the cap and it answers in dates: when the cap runs out at this pace, and how many days the fixes buy back.

optimaizr profile --budget 300
  Monthly cap               $300.00  resets Oct 1 (UTC)
  Used this month           $246.40  ████████████████░░░░ 82% · day 22 of 30
  At this rate               Sep 27  cap reached 4 days before reset
  With the fixes below       Sep 28  +1 day · estimated

optimaizr live --budget 300 warns once each at 50%, 80%, 95% and 100%. The month is cut in the --tz zone, UTC by default. It counts calls on this machine only, so usage elsewhere brings the real cap sooner.

Claude Pro, Max or Team. On a flat plan the dollars are what the same work would cost on the API, which is still the right measure of a session: a larger model drains one faster in roughly the proportion it costs more. Your plan is detected from Claude Code’s own sign-in, reading only the plan fields; when the tier is not reported it asks rather than guesses. To override it: pro ($20), max5 ($100), max20 ($200), team ($25 a seat) or team-premium ($125 a seat), at monthly list prices. On Enterprise the seat comes with usage billed at API rates under a spend limit, so the dollars are the bill: use --budget with that limit instead.

optimaizr profile
  API-equivalent         $443.55/mo  22x what you pay
  5-hour sessions                18  in the last 30 days
  Waste per session             10%  fix it and you'd hit the limit ~11% later
  Your session limit        ~$26.90  learned from 3 recorded hits
  This session               $12.40  since 20:00, resets 01:00 · ~46% of it

Anthropic does not publish the limit, so it is learned: run optimaizr limit when Claude says you have hit it (--at 15:10 after the fact, undo to take one back). live then warns at 80% and 95% of it. Sessions are rebuilt from timestamps, five hours from the top of the hour. With the Claude Code mod running, profile and live show Claude Code’s own 5-hour and weekly meters instead.

Any ChatGPT plan. Nothing to set: Codex records OpenAI’s own limit meter in its session files, so profile shows your plan, the share of each window used (5-hour and weekly on Plus) and when each resets, next to the waste. live warns at 80% and 95% of each. Free ($0), Go ($8), Plus ($20), Pro 5x ($100) and Pro 20x ($200) are priced; Business, Enterprise and Edu seats are not, because their price depends on billing and seat type, so they show no multiple.

optimaizr profile
  ChatGPT Plus            $20.00/mo  what you pay
  API-equivalent         $117.72/mo  5.9x what you pay
  5-hour window                 82%  used · resets 01:49
  Weekly window                 38%  used · resets Sep 25, 22:49

Set either once in config: { "budget": 300 } or { "plan": "pro" }. ChatGPT plans need no setting.

10Verifying a fix

Cheaper, and still good

Anyone can tell you a cheaper model is cheaper. verify checks it still does the job, on your own traffic, before you change anything.

optimaizr verify model-fit
   PASS   40 samples replayed

  cost/call   $0.0121 -> $0.0034
  projected   $61.40/mo saved
  this check cost you $0.38
  1. Replay, not simulation. Recorded requests are re-sent under the change and compared with the production response.
  2. Deterministic checks first. JSON parses, required fields exist, the same tool is called, length stays in budget.
  3. Then a pairwise judge, each pair judged twice with positions swapped, so position bias cannot pick a winner.
  4. A failure is a result. If the cheaper option is worse, you are told to keep what you have.

Verification needs prompts, so turn on capture: opt-in, sampled, redacted, local.

app.ts
optimaizr.wrap(client, { service: "checkout-api", capture: { rate: 0.02 } });

Fixes that change behaviour without being a request rewrite (giving small jobs their own context, say) cannot be replayed. apply <rule> --accept-risk records your sign-off instead.

11What it catches

Fourteen detectors

cache-churnA prefix that changes between calls, so caching never pays off
repeat-tool-callsFiles re-read inside one session, re-billed on every later call
model-fitMechanical turns running on a model priced for reasoning
reasoning-effortHeavy deliberation that produced almost no output
oversized-tool-outputTool results large enough to distort a whole session
error-loopsThe same failing command retried unchanged
prompt-bloatAn oversized system prompt paid for on every call
repeated-contextThe same prefix re-sent across separate sessions
oversized-inputSmall jobs inheriting a whole session's context
oversized-outputResponses far longer than the median
cold-resumeComing back to a long conversation after its cache expired
spend-concentrationA few workloads driving most of the bill
cost-spikeA sudden increase that call volume does not explain
pricing-changeRates changing under you

Findings are safe to apply (pure waste removal) or need verification (could change output). Rate increases you have to absorb are reported separately and never counted as savings.

12Getting it right

Where naive cost tools go wrong

  • Transcripts double-count. Claude Code stamps every content block with the same usage; summing rows inflates spend about 1.9x. optimAIzr keeps one per response.
  • Images are priced by pixels. Real dimensions come from the image header, not from the base64 length.
  • Prices are dated. Each call is costed at the rate in force that day, including cache reads, cache writes and batch discounts.
  • Per-request charges count. Web search is billed per search and priced as its own line.
  • Open models count too. DeepSeek V4, GLM, Kimi and MiniMax M3 through opencode are priced from each vendor's own list: DeepSeek at half price off-peak, MiniMax M3 with its long-context rate, the free GLM models at $0. They are never suggested as a switch. A model with no price takes what opencode recorded for the call, and calls nothing could price are counted as $0 with the models named, so a gap never passes for a cheap month.
  • “At this rate” is the recent rate. Past 30 days of history, monthly figures project the last 30, not an average that lets April dilute September.
  • Days need a timezone. Buckets default to UTC; pass --tz local or any IANA zone.
What the headline is not. It is estimated API-equivalent spend: list rates applied to recorded tokens. Not an invoice, and a Claude subscription or plan meter counts usage differently. Use it to compare your traffic against itself.
13Configuration

Your quality bar, your prices

Read from optimaizr.config.json or .optimaizr.json in the current directory, then ~/.optimaizr/config.json.

optimaizr.config.json
{
  "qualityBar": {
    "sampleSize": 40,
    "checks": [
      { "type": "json-parses" },
      { "type": "contains", "value": "summary" },
      { "type": "max-chars", "value": 2000 }
    ],
    "judge": {
      "model": "claude-opus-5",
      "criteria": "Which response is more accurate and complete?",
      "minWinRate": 0.45
    }
  }
}

Prices are data. Add a model, a price change or a whole provider with no code change:

~/.optimaizr/models.json
[
  {
    "id": "acme-turbo-1",
    "label": "Turbo 1",
    "provider": "acme",
    "tier": "fast",
    "rates": [{ "from": "2026-01-01", "inputPerM": 0.5, "outputPerM": 1.5 }],
    "contextTokens": 128000,
    "maxOutputTokens": 8000,
    "capabilities": ["tools"],
    "bestFor": "Cheap bulk work."
  }
]

Gemini is built but off until its rate cards are verified. Enable it with OPTIMAIZR_GEMINI=1.

14Data handling

Your usage never leaves your machine

  • Analysis is entirely local. No account, no telemetry, no upload.
  • Data lives in ~/.optimaizr/ as plain JSONL. Delete the folder to remove everything.
  • The network calls are verify, to your own provider with your own key, which is never stored or logged, and a once-a-day request to npm for the latest version number, which sends nothing about you (off with OPTIMAIZR_NO_UPDATE_CHECK=1).
  • Prompt contents are never stored unless you turn on capture, apart from guard's short-lived handoff note.
  • Every change, made by optimAIzr or recorded by you, goes into changes.jsonl: which change, to what and when. No usage, prompts or code.
  • The status line logs the time and the percent each time Claude Code's 5-hour meter moves, to meter.jsonl, and Claude Desktop's plan-usage-history.json is read too. From both, window-rate.json keeps what 1% of the window costs, for live and the mod.
  • The Claude Code mod reads usage figures and the commands Claude runs, never your prompts or file contents, and makes no network calls.
  • Guard reads the end of the conversation's transcript at each message and tool call, in memory. When it holds a message it saves the note (the last ask, files changed, what was tried and dropped, open todos, a clip of the last reply) in guard/handoffs/, read once by the /clear it was made for and then deleted; a note nobody reads goes after 30 minutes. What it held goes to guard/receipts.jsonl: when, what kind, the cost, and the file or command. It makes no network calls.
  • HTML reports are self-contained and fetch nothing when opened.

Run optimaizr privacy for the full answer, or read the privacy policy. verify needs the optional @anthropic-ai/sdk or openai package, and reads ANTHROPIC_API_KEY or OPENAI_API_KEY.