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.
- Use it when you want the token detail behind a cost figure, need it for a script or a spreadsheet, or want to see which backend an actor's tokens went to.
- Use something else when you want what the work cost and the levers that would lower it (
hero efficiency), or which model served each call and which calls moved (hero route). - Advanced:
hero helpdoesn't listhero usage, and it has no help page of its own. See Limits. - Reads or changes: reads only. It changes none of your work or settings, and makes no network call.
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
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--days <n> | Whole number | No | 30 | A whole number | How 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> | Text | No | Every actor | An actor as the record stores it | Shows one actor's rows only. Calls through the model gateway are recorded with the actor local:operator. |
--backend <name> | Text | No | Every backend | A backend name, such as the provider that served the calls | Shows one backend's rows only. The --json output lists the backends Agent OS knows in backends. |
--source <label> | Choice | No | Every label | measured, estimated, unavailable | Shows rows with that source label only. Any other value is ignored, and every row is shown. |
--json | Flag | No | Off | None | Prints 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.
See the last 30 days.
hero usageYou should see the header, the rate card line,
LANES (all actors),ROWS, thenTOTAL:andCALL TOTAL:. With no calls in the window, it prints(no usage rows in window).See the last day only.
hero usage --days 1You should see the same sections, for the last day.
See only the counts your provider reported.
hero usage --source measuredYou 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
| Part | What it means | What to do |
|---|---|---|
| Header | The report's name, and that calls are counted in the hour they started. | Nothing. |
| Rate card line | The 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. |
ROWS | One 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 column | The 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 BASIS | The 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 rows | Says 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
| Code | Meaning for this command | Cause | What to do |
|---|---|---|---|
0 | The report printed | Including an empty window, and a partial read the note describes. | Read the note, if there is one. |
2 | Refused | An argument it doesn't take, or a flag with no value. | Check the synopsis. |
3 | The record of model calls is unreadable | No line of the record could be read. | Email support at the address in your welcome email, with the output you saw. |
| Error | Cause | Fix |
|---|---|---|
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 rows | The 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
| Name | Kind | Purpose |
|---|---|---|
HERO_BILLING_RATES | Environment variable | Path to your own rate card. Dollar figures use it. Without it, they use public list prices, and the header says which. |
HERO_HOME | Environment variable | Root of the record hero usage reads. Default ~/.hero. |
Limits of hero usage
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| No help page | hero usage isn't listed in hero help, and its help forms print the general help page. | No | Use this page. |
| Some bad values are ignored | A --days value that isn't a whole number, and a --source value other than the three labels, are ignored without a warning. | No | Check the window and labels in the output. |
| Which calls it covers | Calls 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. | No | Check which agents use the model gateway with hero route census. |
| Dollar figures are estimates | Worked out from the rate card when you run the report. They aren't your invoice. | Yes: point HERO_BILLING_RATES at your own rates | See Use your own rates. |
| Hourly buckets | A call counts in the hour it started, even if it ran past the hour. | No | Nothing. |
| The actor flag's name | The flag is --seat, and the JSON field is seat, though the screen says actor. | No | Use --seat with the actor value the record stores, such as local:operator. |
Commands related to hero usage
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.