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

hero route

Shows which model served each of your agents' model calls, which calls moved, and where your tokens went.

What hero route does

It answers one question: what did routing do with my agents' model calls? It reads the record Ekamyth Agent OS keeps on your machine of each call, and shows the requested model, the model that served it, and whether the call moved. hero route census answers a second question: which of my agents send their calls through Agent OS at all?

Each row is one metered record, not a distinct call. Lines with no evidence behind them print not measured with a reason, never $0. Cost is an estimate at public list prices, unless HERO_BILLING_RATES points at your own rate card. The output says which.

Synopsis for hero route

hero route [status] [--since <time>] [--all] [--only <word-or-model>] [--json] [--details]
hero route list [--since <time>] [--all] [--only <word-or-model>] [--json] [--details]
hero route census
hero route describe [--json]
hero route help

Run with no subcommand, it behaves as status. hero route -h is the same as --help.

Subcommands of hero route

SubcommandWhat it doesReads or changes
statusWhether routing is working, what moved, where your tokens went, which models ran each kind of work, and the newest 20 records. It asks the model gateway whether it's answering. This is the default.Reads
listThe same view, titled Route · newest <n> records, without asking the model gateway. Up to 200 records with --all. Totals always cover the full window.Reads
censusWhether this install's model gateway is answering, the calls it logged in the last 24 hours, and, for each known agent, whether it sends calls through the gateway.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 route.Reads

Arguments for hero route

Arguments for status and list

ArgumentTypeRequiredDefaultWhat it does
--since <time>A UTC instant, <n>h, <n>d or todayNoLast 24 hoursShows records from that time until now, up to 30 days ago. A UTC instant must have offset zero, such as 2026-11-04T00:00:00Z. today means 00:00 UTC. Attribution reads as unverified.
--jsonFlagNoOffMachine-readable output with data and envelope. list --json adds next_cursor. JSON never asks the model gateway. Combines with --details.
--detailsFlagNoOffShows every shared number as numerator/denominator, with the reasons a figure is partial.

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

More arguments for status and list

ArgumentTypeRequiredDefaultWhat it does
--allFlagNoOff, newest 20Shows every record up to 200. Totals always cover the full window.
--only <value>violations, blocked, failed, or a model nameNoOffFilters the list of records. A model name must be a model Agent OS knows, and matches records where it was the requested or the served model. Text view only: with --json it's refused. See Limits for the three words.

Arguments for census

None. Any argument, including --json, is refused with exit code 2.

How hero route gets its answers

Agent OS keeps a record of each model call on your machine: the requested model, the model that served it, whether it moved, the kind of work, tokens and estimated cost, with no prompt or response text. hero route reads that record, prices the calls against the rate card, and prints the result. status in your terminal also asks the model gateway whether it's answering, so it can say whether routing is working. list and every --json call skip that check. For the whole picture, see How routing works.

Your agent's model call goes through Agent OS, which keeps the requested model or moves the call, then to your provider. hero route shows each call in your terminal.
What hero route shows is what happened to your own calls.

Get started with hero route

Before you start: Agent OS is installed and you've run hero setup. With no calls recorded yet, the summary says No model calls yet.

  1. Check that your agents send their calls through Agent OS.

    hero route census

    You should see each known agent with a mark and the evidence for it. After hero setup, claude-code and codex should read ✓ VIA-PROXY. See Example 1.

  2. See recent calls and what routing did.

    hero route

    You should see the window, whether routing is working, what moved, where your tokens went, and the newest records. See Example output.

  3. See every record in the window.

    hero route list --all

    You should see up to 200 records, and totals for the full window.

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

Example output of hero route

Output from version 0.1.36rc13, from a test run of four model calls through a local test server. Lines are left out where you see …; no number is changed. Dollar figures are left out.

When net saving can be measured, hero route shows it at public list rates; otherwise it says "not measured". The Net saving line prints Net saving at public list rates: $<n>, or Additional cost at public list rates: $<n> when the moves cost more. Both are estimates, not invoice or subscription savings.

When a call that was moved to another model fails, the savings figure can overstate. The 'net saving at public list rates' figure can also overstate savings when calls move because a model was unavailable. Treat it as an estimate.

How to read hero route output

Lines 5 and 8 aren't in the excerpt above. The run had too few records for line 5, and line 8 is left out because it holds token totals.

LineWhat it meansWhere it comes fromWhat to do
1. WindowThe window every figure covers, last 24 hours by default. partial means some figures aren't fully measured.Your local call record.Use --since for another window, or --details to see what's partial.
2. RecentThe newest records. Each row is one metered record, not a distinct call.Your local call record.Use --all to expand recent detail to at most 200 records, or --since <when> to choose a time window.
3. A kept callWhen, the kind of work (see line 9), the model that served it, and its cost. (kept) means the requested model served it. — means the cost wasn't recorded, and <$0.01 means less than a cent.Your local call record, priced on the rate card.A kept call used the requested model; the kept status alone requires no action.
4. A moved callThe model that served it and the model your agent asked for, then a reason word, such as reason right_sized. right_sized: moved to a smaller model because measured evidence says it does this kind of work as well. cost-min: moved to the lowest-priced model that meets the call's needs. best-fit-fallback: chosen by capability and price, because there's no quality measurement for this kind of work yet. It isn't a failover.Your local call record.A moved call needs nothing from you. Read the reason word on the line. To stop moves, set HERO_ROUTE=0 (all moves), HERO_ROUTE_LADDER=off (keeps only the background moves) or HERO_ROUTE_CLASSIFY=0 (every move based on the kind of work).
5. OlderHow many older records the list leaves out.Your local call record.Use --all or --since.
6. Is it workingWhether routing is on and the model gateway is answering, and how many records changed model.Your local call record and the model gateway.If the gateway isn't answering, start it.
7. What it downgradedMoves, and their estimated effect at public list prices or your rate card.Your local call record and the rate card.Read the figures as estimates, not invoice or subscription savings. The header's saving is gross: saved on calls moved to a cheaper model, same tokens, or cost ? when no priced baseline was recorded. A row's saved cell is a ~ estimate unless it is reconciled, or it reads not enacted, failed, outcome ? or cost ?. When nothing moved, the section reads nothing downgraded — <why>.
8. Where your tokens goInput and output tokens by the model that served the calls, with the estimated spend at public list prices or your rate card.Your local call record, priced on the rate card.For cost across every lever, run hero efficiency.
9. Models by task classHow many records each model served for each kind of work. The kind of work Agent OS inferred for each call.Your local call record.No action is required for this table alone.
10. Review routing coverageCommands to narrow the view.The report.Run one.

More hero route examples

Example 1. To check which agents go through Agent OS

hero route census

Example output. The format is the command's; the numbers are examples. Excerpt: paths are shortened, and lines left out are marked ….

hero route census — what routes via the proxy, what bypasses it

  proxy state
    :18500  UP       this install's Runtime — healthz ok
    …

  traffic via proxy (last 24h)
    none recorded in the structured log

  known surfaces
    ✓ claude-code     VIA-PROXY  base URL points at this install's Runtime (http://127.0.0.1:18500)
      evidence: …/.claude/settings.json
    …
    ✓ codex           VIA-PROXY  base URL points at this install's Runtime (http://127.0.0.1:18500/v1)
      evidence: …/.codex/config.toml
    …
    ? cloud-sessions  UNKNOWN    cloud session routing is not derivable from this machine
      evidence: (no local evidence)

  2 of 5 known surfaces route via proxy.

Each agent reads ✓ VIA-PROXY or ? UNKNOWN, with the file or setting that shows it. UNKNOWN always comes with its reason.

Example 2. To see every record in a time range

hero route list --since 6h --all

This prints the records from the last six hours, up to 200, with totals for the whole range. With nothing recorded, the window line reads <time> → now · unavailable and adds attribution unverified — since_window_not_session_bound.

Example 3. To see the calls one model handled

hero route --only claude-sonnet-5

This lists the records where claude-sonnet-5 was the requested or the served model.

Example 4. To use the numbers in a script

hero route --json

Its data holds headline, the title line; runtime_answering, which is null because JSON doesn't ask the model gateway; policy, which reads "unknown" for the same reason; and next_step, null unless one applies. list --json puts the records in data and adds next_cursor.

Routing off

Start or restart the model gateway with HERO_ROUTE=0 in its environment to turn automatic routing off.

Exit codes and errors for hero route

CodeMeaningWhat to do
0The output asserts a positive result, or is advice with no verdict.Nothing.
1A truthful negative result.Read the output.
2Refused: unknown flag or subcommand, missing argument, not configurable, or unavailable.Read the governing_rule line and run the remedy, usually hero route --help. See 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
route has no verb '<word>'An unknown subcommand.Check the synopsis.
route has no flag '<flag>'An unknown flag.Check the synopsis.
route is not configurableAn attempt to switch hero route on or off.None. See Routing off.
route selectors apply only to status and list--since or --session was used with another subcommand, such as census.Use them with status or list.
invalid_since, invalid_window--since isn't a form it reads, such as yesterday or a +02:00 offset, or is more than 30 days ago, such as 40d. The rule reads Route selection requires a UTC instant within 30 days, or repeatable sessions; narrow the window for a query limit.Use a UTC instant, <n>h, <n>d or today, within 30 days.
route describe takes only --json (got '<flag>')describe was given another flag.Use hero route describe --json.
--only must be violations, blocked, failed, or a model name (got '<value>')--only was given something else.Use one of the three words or a model name.
hero route census: unexpected argument(s): <args>census was given an argument, such as --json.Run hero route census with no arguments.

Files and environment for hero route

NameKindPurpose
HERO_BILLING_RATESEnvironment variablePath to your own rate card. Cost and saving figures use it. Without it, figures are at public list prices, and the output says so. See Use your own rates.
HERO_PROXY_PORTEnvironment variableThe model gateway port that status and census check. Default: this install's port, otherwise 8081.
HERO_BEACON=offEnvironment variableData reads can send the usage beacon. Usage reporting is on by default. It sends metadata only — never content, prompts or responses — at most once a day. Turn it off with HERO_BEACON=off.
HERO_HOMEEnvironment variableRoot of Agent OS's files on your machine. Default ~/.hero.
~/.claude/settings.json, ~/.codex/config.tomlFiles, read by censusYour agents' settings, which show whether each one points at the model gateway.

Limits of hero route

LimitBehaviourCan you change it?What to do
WindowLast 24 hours by default. --since goes back 30 days at most.Up to 30 daysUse --since.
Rows shownThe newest 20 by default, 200 at most with --all. Totals always cover the full window.Up to 200Use --all or a shorter --since.
--sessionCalls aren't linked to sessions, so it shows no data for a session. The output says session binding not installed.NoCalls are not linked to sessions in this routing report, so session-level results are not measured.
--only violations, blocked, failedRouting records carry no blocked or failed outcome, so these match nothing.NoUse a model name, or see refusals in hero trace.
Failed and fallback callsA call that failed, was refused or fell back can read as (kept).NoSee refusals in hero trace.
Models routing doesn't knowA call to a model routing doesn't know is not moved and has no list price. Its spend can read ~$0.00 metered spend, which is not its real cost.NoRead the No public list price line for the models this applies to.
Busy recordUnder heavy load, hero route --since 1h can be refused with query_limit.NoRun it again, or use a shorter window.
Calls refused before sendinghero route list can name a model as having served a call that Agent OS refused before sending it, for example when no agent session was ready or sign-in failed.NoSee refusals in hero trace.
census trafficcensus can show no traffic even when calls were routed.NoUse hero route to see the calls.
census errorsAn error from census goes to the terminal's error output, not as a refusal object. shell-sessions reports only the shell you run it in.NoRun census from the shell you want checked.
Lines with no evidenceMany summary lines read not measured, some with a raw reason code.NoUse --details to see the reason for each.
/hero:route in your agentInstalled by setup.NoRun hero route in your terminal.

How calls may move

Which calls may move

Routing sends each kind of work to the least expensive model we expect to do it well, and it keeps learning from outcomes. Every call shows the model you asked for and the model that answered, so you can always see what happened. Every call that moved comes with a receipt, and hero route lists it with its reason. For Codex calls, hero route also shows how they're handled on its Codex agentic floor line, for example:

Sample output (simulated data). One line of hero route.

Codex agentic floor: off — native Codex keeps the requested model (HERO_ROUTE_CODEX_AGENTIC_FLOOR_TIER is not set on the Runtime)

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