Ekamyth Agent OS docs
Added for agents / Right model, right cost

hero efficiency

Shows what your agent work costs, and which levers would cut it.

What hero efficiency does

It answers one question: why is my agent expensive, and what do I fix? It reports on the last 30 days of calls recorded on your machine. It prices them, then shows twelve savings levers: what each has already saved and what it could still save, where there's evidence.

All savings and cost figures in Agent OS are at public list prices, including the "saved" line. Spend is an estimate, not your provider's bill, unless your own rate card prices every call. Lever figures are never added together. Unavailable means there isn't enough evidence. It never means $0.

Synopsis for hero efficiency

hero efficiency [status] [--json] [--details]
hero efficiency [status] [--since <utc-time>] [--json]
hero efficiency list [--table] [--json] [--details]
hero efficiency list [--since <utc-time>] [--json]
hero efficiency billing [<path>]
hero efficiency describe [--json]
hero efficiency help

Run with no subcommand, it behaves as status.

Subcommands of hero efficiency

SubcommandWhat it doesReads or changes
statusEstimated spend over the last 30 days, what Ekamyth Agent OS saved, the top moves and one next step. This is the default.Reads
listThe table of twelve savings levers, with the rate card, a guide to reading it and one recommended next action.Reads
billingChecks a rates file and prints what it would price. It saves nothing. See Example 3.Reads
describeThe command's own descriptor. Reads none of your data and sends no beacon.Reads
helpThis command's help. Same as --help and hero help efficiency.Reads

Arguments for hero efficiency

Arguments for status and list

ArgumentTypeRequiredDefaultWhat it does
--jsonFlagNoOffMachine-readable output with data and envelope. list adds next_cursor. With --since, the output is data only, with at most 50 detail rows.
--detailsFlagNoOffShows every shared number as numerator/denominator, with the reasons a figure is partial and the rate card version. On status it replaces the default view with this evidence view.
--since <utc-time>ISO-8601 time, UTCNoRolling 30 daysSwitches to the THIS JOB view for calls from that time until now. It must be in the past and within the last 30 days, and attribution reads as unverified.

hero efficiency --help also lists --session. See Limits.

Arguments for list only

ArgumentTypeRequiredDefaultWhat it does
--tableFlagNoOffWith --json, returns the whole table object. It doesn't change the human output.

Arguments for billing

ArgumentTypeRequiredDefaultWhat it does
<path>File pathNoThe file named by HERO_BILLING_RATESThe rates file to check. With neither, it prints the usage and file format, and exits 1.

How hero efficiency gets its numbers

Agent OS records what each of your agents' model calls costs, on your machine: the model and the tokens, never your prompts or responses. hero efficiency prices those calls at public list prices, or your own rates, and reports spend and what each lever found. See How Efficiency works.

Your agent's model calls pass through Agent OS on your machine to your provider. Agent OS records the cost of each call. hero efficiency shows spend and levers, and you decide what to change.
What Efficiency records stays on your machine and holds no prompt or response text.

Get started with hero efficiency

Before you start: Agent OS is installed. With no calls recorded, you'll see the first view under Example output.

  1. See your estimated spend.

    hero efficiency

    You should see a window, a call count, and spend or "nothing measured yet". See Example output.

  2. See all twelve levers.

    hero efficiency list

    You should see one row per lever. See Example 1.

  3. See the evidence behind each number.

    hero efficiency --details

    Each shared number appears as numerator/denominator, followed by the reasons any figure is partial.

Nothing here changes your work, so there's nothing to undo.

Example output of hero efficiency

Before any calls are recorded

Output from version 0.1.36rc13. Trimmed where you see …

With recorded calls

Sample output (simulated data). 30 days of Claude Code and Codex calls. Lines with dollar amounts are left out where you see …

Efficiency · rolling 30d (Oct 09–Nov 08 UTC) · 311 calls
  …
  311 metered records (incl. 0 evaluation replays)
  Ekamyth Agent OS saved       unknown not measured — the price of the model you
                                       asked for wasn't recorded (7 buckets not
                                       measured yet)

WHERE THE SAVING CAME FROM
  We bring efficiency with all these levers. We are still measuring their
  impact.
  Routing                      unknown not measured — the price of the model you
                                       asked for wasn't recorded
  Rules as code (codify)       not measured yet
  Failures and retries avoided not measured yet
  Context and memory trimming  not measured yet
  Output compression           not measured yet
  Tool and reasoning waste     not measured yet
  Right-sized agents           not measured yet
  Our part of caching          not measured yet
  …

IS IT REAL?
  Measured    model and tokens (311 of 311 calls)
  Quality not measured for these calls
  18 of 311 metered records changed model (record count, not distinct calls)
  Not netted  on 49 calls the Runtime changed request bytes, which can cost
              provider-cache discount (314k tokens, not priced yet)

TOP MOVES
  newest 50 of 311 records read · counts cover only these
  gpt-5.4 → gpt-5.4-mini · 3 moved records · cost-min
  claude-opus-4-8 → claude-sonnet-5 · 1 moved record · cost-min

NOT SAVED YET  6 levers with an opportunity · 3 not priced — no price for this
               lever's evidence · your agent could change: blind retries, long
               outputs, repeated tool calls, calls still on the expensive model
               · --details
NEXT STEP      In your agent: have your agent change the request before it
  …

The saved line and the Routing line read not measured when the price of the model your agent asked for wasn't recorded, even with many calls recorded. hero efficiency prints what it measured and leaves the rest as not measured.

In TOP MOVES, the word after each move is the reason. cost-min: the cheapest model that fits the call. right_sized: moved to a smaller model because measured evidence says it does this kind of work as well.

When a call that was moved to another model fails, the savings figure can overstate.

More hero efficiency examples

Example 1. To see the savings levers

hero efficiency list

Example output. The format is the command's; the numbers are examples. Excerpt: the lever table only, before any calls are recorded.

EFFICIENCY LEVERS
  ┌─────────────────────┬─────────────────┬────────────────────┬─────────────┐
  │ Lever               │ Already saved   │ Opportunity        │ Status      │
  ├─────────────────────┼─────────────────┼────────────────────┼─────────────┤
  │ Codify              │ Unavailable     │ Unavailable        │ UNAVAILABLE │
  │ Route               │ not measured —  │ Unavailable        │ UNAVAILABLE │
  │                     │ the price of    │                    │             │
  │                     │ the model you   │                    │             │
  │                     │ asked for       │                    │             │
  │                     │ wasn't recorded │                    │             │
  │ Memory              │ Unavailable     │ Unavailable        │ UNAVAILABLE │
  │ Caching             │ Unavailable     │ Unavailable        │ UNAVAILABLE │
  │ Retries             │ Unavailable     │ Unavailable        │ UNAVAILABLE │
  │ Output size         │ Unavailable     │ Unavailable        │ UNAVAILABLE │
  │ Tool duplication    │ Unavailable     │ Unavailable        │ UNAVAILABLE │
  │ Over-thinking       │ Unavailable     │ Unavailable        │ UNAVAILABLE │
  │ Eval coverage       │ Unavailable     │ Unavailable        │ UNAVAILABLE │
  │ Prefix alignment    │ Unavailable     │ Unavailable        │ UNAVAILABLE │
  │ Content compression │ Unavailable     │ Unavailable        │ UNAVAILABLE │
  │ Agent right-sizing  │ Unavailable     │ Unavailable        │ UNAVAILABLE │
  └─────────────────────┴─────────────────┴────────────────────┴─────────────┘
ColumnWhat it means
Already savedRealized savings against a named baseline. A move to a more expensive model is never counted.
OpportunitySavings found but not yet realized, priced on that lever's own basis. Never added across levers.
StatusACTION: a positive, evidence-qualified opportunity. CLEAR: no current evidence of waste, which isn't proof there's none. UNAVAILABLE: not enough evidence.

To see what each lever looks for, see What Efficiency looks for.

Example 2. To see what's recorded for a time range

hero efficiency --since 2026-11-01T00:00:00Z

This prints the THIS JOB view, not the default view. It has no "You spent" line. It shows the first and last call and the record-level lines.

Example 3. To use your own rates

Create a rates file:

{"claude-haiku-4-5": {"in_per_mtok": 0.80, "out_per_mtok": 4.00}}

Check it, then set it:

hero efficiency billing ~/rates.json
export HERO_BILLING_RATES="$HOME/rates.json"
hero efficiency list

billing will:

  • Check the file and print what it would price. It saves nothing.

The export will:

  • Make that rate card apply in that shell, for any command you run from it.

Example output. The format is the command's; the numbers are examples. Excerpt: the closing lines from billing.

Checked, not saved — hero reads your rates from HERO_BILLING_RATES. To use them:
  export HERO_BILLING_RATES=<abs path>
  (models the card does not list stay `cost ?`; a partial card is never shown as reconciled)

To verify, read the first line of hero efficiency list: it says reconciled · rates from <path> when your card prices every call. If the card misses a model, it says partial, not reconciled. To go back to list prices, unset the variable.

Each model takes in_per_mtok and out_per_mtok, and optionally cache_read_per_mtok, cache_creation_per_mtok and cache_creation_1h_per_mtok.

Example 4. To use the numbers in a script

hero efficiency --json

Exit codes and errors for hero efficiency

CodeMeaningWhat to do
0The output asserts a positive result, or is advice with no verdict.Nothing.
1A truthful negative result. For billing: no path and no HERO_BILLING_RATES, or the file wasn't found.Read the output. For billing, give it a file that exists.
2Refused: unknown flag or subcommand, missing argument, unusable rates file, or not available.Check the synopsis and the errors below.
3A source it needs is unavailable at runtime.Email support at the address in your welcome email, with the output you saw.
ErrorCauseFix
invalid_since--since isn't an ISO-8601 UTC time, for example --since yesterday.Use a form like 2026-11-01T00:00:00Z.
invalid_window--since is more than 30 days ago, or isn't in the past.Use a past time within the last 30 days.
billing rates file not found: <path>The rates file isn't at that path.Check the path.
HERO_BILLING_RATES=<path> is not valid JSON — fix the file or unset HERO_BILLING_RATESThe variable points at a file that isn't valid JSON.Fix the file, or unset the variable.
efficiency selectors apply only to status and list--since was used with another subcommand.Use it with status or list.

Files and environment for hero efficiency

NameKindPurpose
Your rates fileJSON file you createYour own prices per model. See Example 3 for the format.
HERO_BILLING_RATESEnvironment variablePath to your rates file. It becomes the rate card. A path that doesn't exist falls back to list prices.

Limits of hero efficiency

LimitBehaviourCan you change it?What to do
Price basisPublic list prices, not your bill. Each model's price carries the date it was read; the card itself is dated 2026-09-09. A partial card is never shown as reconciled.YesSet your own rates.
Models with no list priceCounted, not priced or guessed. A spend amount then shows +.YesSet your own rates.
Routing savingsThe saved line and the Routing line can read not measured, or be wrong.NoRead the spend and call counts; treat the routing saving as provisional.
WindowEvery view covers 30 days at most. --since can't go further back.NoUse --since to choose a shorter window.
--sessionPrints the THIS JOB view with no data for that session, because calls aren't linked to sessions.NoNo action is required from you for this missing measurement; this view cannot yet link these measurements to a session.
Levers with no findingsSome levers read Unavailable for lack of evidence.Only when more evidence is recorded.On a fresh install with nothing recorded, only Eval coverage shows a finding. In a run with sample data, Retries, Output size, Tool duplication, Route and Prefix alignment showed findings too.

Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.