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

hero usage

Shows where your agents' tokens went, by hour, actor, backend, model, kind of work and token type, with the estimated cost of each row and a label saying whether each count was measured.

What hero usage does

It answers one question: where exactly did the tokens go? It reads the record Ekamyth Agent OS keeps on your machine of each model call and rolls it up into rows, one per hour, actor, backend, model, kind of work, turn and token type. Every row carries a source label: measured when the provider reported the count, estimated when Agent OS estimated it, or unavailable when there is no token count at all. A measured count and an estimated one are never added into one number.

Synopsis for hero usage

hero usage [--days <n>] [--seat <actor>] [--backend <name>] [--source measured | estimated | unavailable] [--json]

Any other argument prints the usage line above to the terminal's error output and exits 2. hero usage --help and hero usage help print the general hero help page.

Subcommands of hero usage

None. hero usage is one report, with filters.

Arguments for hero usage

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
--days <n>Whole numberNo30A whole numberHow many days back to report. A negative value reads as 1, and 0 reads as 30. A value that isn't a whole number is ignored, and the report covers 30 days.
--seat <actor>TextNoEvery actorAn actor as the record stores itShows one actor's rows only. Calls through the model gateway are recorded with the actor local:operator.
--backend <name>TextNoEvery backendA backend name, such as the provider that served the callsShows one backend's rows only. The --json output lists the backends Agent OS knows in backends.
--source <label>ChoiceNoEvery labelmeasured, estimated, unavailableShows rows with that source label only. Any other value is ignored, and every row is shown.
--jsonFlagNoOffNonePrints the rows and their metadata as JSON. See Example 2.

How hero usage gets its numbers

Agent OS records each model call that goes through the model gateway: the tokens of each type, the model, the kind of work and when the call started, with no prompt or response text. hero usage brings its local index up to date with that record, then rolls it up by hour, with each call counted in the hour it started.

It can also read Codex's own session logs, so that Codex activity shows up, but only with your consent. You give it in setup's history question, or with hero history on from your own terminal. hero history off stops further reading and keeps what was already imported, and hero history forget also removes the imported history. If you set HERO_CODEX_LOGS to a path, Agent OS reads that path on its own, so remove that setting too when you withdraw.

Dollar figures are worked out when you run the report, from the rate card: public list prices, or your own rates when HERO_BILLING_RATES points at a rate card. The header names the rate card. A model or token type with no rate shows —, never $0.00. A count labelled unavailable is never priced.

An actor and backend that were active but reported no tokens get their own row, labelled unavailable, with a null token count, so an active backend never disappears from the report.

Nothing leaves your machine. hero usage reads local files only.

Get started with hero usage

Before you start: Agent OS is installed, hero setup has run, and your agent has made model calls through the model gateway since. These commands work the same on Mac and Linux.

  1. See the last 30 days.

    hero usage

    You should see the header, the rate card line, LANES (all actors), ROWS, then TOTAL: and CALL TOTAL:. With no calls in the window, it prints (no usage rows in window).

  2. See the last day only.

    hero usage --days 1

    You should see the same sections, for the last day.

  3. See only the counts your provider reported.

    hero usage --source measured

    You should see rows labelled [measured] only.

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

Example output of hero usage

Output from version 0.1.36rc13. Trimmed where you see …

hero usage — tokens per actor-hour / backend-hour (calls bucketed by request
  start time)
  rate card vpublic:cce34f1281b4 · estimated (public list rates ·
    https://platform.claude.com/docs/en/about-claude/pricing ·
    https://openai.com/api/pricing/ ·
    https://ai.google.dev/gemini-api/docs/pricing · as-of 2026-09-09)

LANES (all actors)
  actor local:operator  anthropic     [measured]  tokens=…
  actor local:operator  openai-codex  [measured]  tokens=…

ROWS (hour · actor · backend · model · class · turn · type · source · tokens · $ · billable)
  2026-11-06T05:00:00Z  actor local:operator  anthropic     claude-sonnet-4-5  background-utility  new-question  input   [measured]  12  $0.0000  [basis 1]  provider_exclusive
  2026-11-06T05:00:00Z  actor local:operator  anthropic     claude-sonnet-4-5  background-utility  new-question  output  [measured]   3  $0.0000  [basis 1]  provider_exclusive
  2026-11-06T05:00:00Z  actor local:operator  openai-codex  gpt-5-codex        chat                new-question  input   [measured]  12        —             partitioned
  2026-11-06T05:00:00Z  actor local:operator  openai-codex  gpt-5-codex        chat                new-question  output  [measured]   3        —             partitioned

PRICE BASIS
  [basis 1] estimated (public list rates ·
    https://platform.claude.com/docs/en/about-claude/pricing · as-of 2026-09-09)

TOTAL: …
CALL TOTAL: 2 calls

Prices in this output are estimated, at public list prices.

How to read hero usage output

PartWhat it meansWhat to do
HeaderThe report's name, and that calls are counted in the hour they started.Nothing.
Rate card lineThe rate card behind every dollar figure: its version and its price status.To use your own rates, see Use your own rates.
LANES (all actors)One line per actor and backend: the actor, the backend, the source label in brackets, and tokens= the total. tokens=null means the backend was active but reported no tokens. (no actor) means the calls carry no actor.Use --seat or --backend to see one lane's rows.
ROWSOne line per hour, actor, backend, model, kind of work, turn, token type and source label, with the token count, the dollar figure, a [basis <n>] reference to the price basis, and the billable basis. Turn: new-question is a user message without tool results, error-recovery follows a tool result marked failed, routine-resume follows a tool result without that mark, unknown means the call had too little recognizable structure, and - means no turn was recorded. Billable basis: partitioned means cache-inclusive input was split into billed quantities that don't overlap, provider_exclusive means the provider's input already excludes cache quantities, unresolved means the provider's accounting couldn't be established, legacy is an older row with no split attempted, incoherent means the usage contradicts itself, so there is no trustworthy total, and blank means no basis was recorded. These labels describe measurements, not an invoice.Nothing.
Dollar columnThe estimated cost of the row at the rate card. — means no rate covers it. Another label in its place says why there is no price.Add the model to your rate card.
PRICE BASISThe full text behind each [basis <n>] reference.Nothing.
TOTAL:The tokens in the window. Measured and estimated tokens are shown as separate parts, never added together.Compare with hero efficiency.
CALL TOTAL:The number of calls in the window. Shown when it can be counted.Nothing.
A note after the rowsSays when the rows are partial: some lines of the record couldn't be read, the index is still catching up, or a read limit was reached.Run it again later. If lines can't be read, see Exit codes.

More hero usage examples

Example 1. To see one backend for the last week

hero usage --days 7 --backend <name>

This shows the rows for that backend over seven days. Backends include anthropic and openai-codex.

Example 2. To use the rows in a script

hero usage --json

It prints rows, days, fields, backends and note. Each row has exactly these fields: hour, seat (the actor), backend, model, task_class, auto_class, turn_kind, token_type, source_label, tokens, calls, usd, usd_label and billable_basis. Token types are input, output, reasoning, cache_creation and cache_read; a row can also carry cache_creation_1h, the part of cache creation billed at the one-hour rate. No row holds a prompt, response, tool argument, file path, session id, provider account or credential. note says how calls are bucketed, and anything partial about the read.

Example 3. To find backends that reported no tokens

hero usage --source unavailable

This shows only the rows with no token count, such as an active backend that reported none.

Exit codes and errors for hero usage

CodeMeaning for this commandCauseWhat to do
0The report printedIncluding an empty window, and a partial read the note describes.Read the note, if there is one.
2RefusedAn argument it doesn't take, or a flag with no value.Check the synopsis.
3The record of model calls is unreadableNo line of the record could be read.Email support at the address in your welcome email, with the output you saw.
ErrorCauseFix
usage: hero usage [--days N] [--seat ACTOR] [--backend NAME] [--source measured|estimated|unavailable] [--json]An unknown argument, or --days, --seat, --backend or --source with no value. Exit 2.Use the forms in the synopsis.
meter unreadable: <reason>, in the note after the rowsThe record of model calls couldn't be read. Exit 3.Email support at the address in your welcome email, with the output you saw.

Files and environment for hero usage

NameKindPurpose
HERO_BILLING_RATESEnvironment variablePath to your own rate card. Dollar figures use it. Without it, they use public list prices, and the header says which.
HERO_HOMEEnvironment variableRoot of the record hero usage reads. Default ~/.hero.

Limits of hero usage

LimitBehaviourCan you change it?What to do
No help pagehero usage isn't listed in hero help, and its help forms print the general help page.NoUse this page.
Some bad values are ignoredA --days value that isn't a whole number, and a --source value other than the three labels, are ignored without a warning.NoCheck the window and labels in the output.
Which calls it coversCalls through the model gateway, and Codex's own session logs with your consent. A call that doesn't go through the model gateway isn't counted.NoCheck which agents use the model gateway with hero route census.
Dollar figures are estimatesWorked out from the rate card when you run the report. They aren't your invoice.Yes: point HERO_BILLING_RATES at your own ratesSee Use your own rates.
Hourly bucketsA call counts in the hour it started, even if it ran past the hour.NoNothing.
The actor flag's nameThe flag is --seat, and the JSON field is seat, though the screen says actor.NoUse --seat with the actor value the record stores, such as local:operator.

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