Ekamyth Agent OS docs
Standard OS / Logs

hero health

Gives one read of how your agents are doing across Govern, Optimize, Assure and Ledger, with a fix for each finding.

What hero health does

It answers one question: how are my agents doing, overall? It reports on the last 30 days recorded on your machine: estimated spend, how many of the four areas are failing, and each finding with its severity and its fix. Each fix is a command to run, or a change to make in your agent.

Spend is an estimate at public list prices, unless HERO_BILLING_RATES points at your own rate card. An area fails when it carries a high finding, and then the command exits 1. What you see depends on your machine: a model gateway that isn't answering is a high finding when Claude Code or Codex is installed, or after hero setup, and a medium finding only on a machine with neither.

Synopsis for hero health

hero health [status] [--json] [--details] [--html]
hero health list [--all] [--details] [--html]
hero health describe [--json]
hero health help

Run with no subcommand, it behaves as status. hero health --help shows --json and --details as a choice; they also combine. See Example 4.

Subcommands of hero health

SubcommandWhat it doesReads or changes
statusThe verdict for each area and every finding in one table, with one command to run next. This is the default.Reads
listFindings, most severe first. The first page of 10 by default.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 health.Reads

Arguments for hero health

Arguments for status

ArgumentTypeRequiredDefaultWhat it does
--jsonFlagNoOffMachine-readable output with data and envelope. data holds the headline, each area's state, and the findings.
--detailsFlagNoOffReplaces the table with the evidence view: the governance posture, each area's state, the top five findings plus any model gateway finding, and the attestation lines. Shared numbers show as numerator/denominator, with the reasons a figure is partial.
--htmlFlagNoOffWrites the report to <HERO_HOME>/report.html (default ~/.hero/report.html), prints report → <path>, and opens the file in your default browser. It overwrites the file each run, and exits with the same code as the text view. It takes precedence over --json.

--all is for list only: status --all is refused. describe takes only --json.

Arguments for list

ArgumentTypeRequiredDefaultWhat it does
--allFlagNoOff, first page of 10Shows every finding, not only the first page.
--detailsFlagNoOffPrints the facts behind the read, with the reasons any figure is partial. It doesn't print the findings.
--htmlFlagNoOffAs for status.

How hero health builds its read

hero health reads what Agent OS has recorded about your agents' work on your machine, across Govern, Optimize, Assure and Ledger. It groups what each capability found by area, sorts the findings most severe first, and gives each one its fix. A standing job runs it daily for you; see hero schedule. For the whole picture, see How observability works.

Agent OS records each session on your machine. Standing jobs run checks on a cadence. hero health gives one read with a fix per finding.
hero health is the one read across everything Agent OS records.

Get started with hero health

Before you start: Agent OS is installed. What you see first depends on your machine. With nothing recorded and no agent installed, you see the first view under Example output. With Claude Code or Codex installed, or after hero setup, and the model gateway not answering, you see a high Govern finding.

  1. See how your agents are doing.

    hero health

    You should see the window, spend, how many areas are failing, and every finding. See Example output.

  2. See the findings, most severe first.

    hero health list

    You should see one row per finding, with its area, severity and fix. See Example 1.

  3. See the evidence behind each number.

    hero health --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 health

Before anything is recorded

Output from version 0.1.36rc13. Trimmed where you see …

Codex users run hero codex.

With recorded work

Example output on a demo home; the numbers are examples. Trimmed where you see …

How to read hero health output

LineWhat it meansWhere it comes fromWhat to do
1, 4. WindowThe rolling 30 days every figure covers, in UTC.Your local records.No action is required for the window label; it identifies the period covered by the report.
2. Nothing measured yetNo agent work has been recorded in the window.Your local records.Use your agent, then run this again.
3. Run, before anything is recordedRun: hero claude. It prints only on an empty install, before the first call.The report.Run it. Codex users run hero codex.
10. RunExactly one command to run next.The report.Run it.
5. SpendTokens, calls and estimated cost in the window.Your local records, priced on the rate card.For cost by lever, run hero efficiency.
6. Areas and findingsHow many of the four areas are failing, how many findings there are, and how many are high. A phrase on your governance posture always follows, such as govern not wired.Your local records.Read the phrase; fixes for findings are in the findings table (line 7). The phrases and what to do: govern enforcing — dangerous actions are refused (nothing to repair); govern builder — records all calls; stops a short list of catastrophic actions (the normal state of a new install); govern observing — dangerous actions pass through; BUILDER floor refuses (if you didn't mean to observe, check the enforcement setting; HERO_GOVERN_ENFORCE=1 in the agent's launch environment asks for enforcement, unless a higher-priority setting overrides it); govern unavailable — the govern owner could not be consulted (look at hero govern); govern not wired — no Ekamyth hook or proxy acts on the policy here (run hero setup, then hero setup --check); govern policy not in force — every agent action is refused and govern policy file broken — only the catastrophic guard is active (run hero govern init, which keeps the bad policy file beside the new one).
7. Findings tableOne row per finding: its area, its severity (HIGH, MED or LOW), what was found, and the fix.What each capability found.Start with the top row.
8. A high findingA high finding makes its area fail, and the command exit 1.What each capability found.Run the command in the fix column.
9. A fix with no commandSome fixes are a change to make in your agent, and say so.What each capability found.Make the change in your agent.
11. Area marksOne mark per area. ✗: failing, with a high finding. !: findings, none high. ✓: no findings, and real activity was measured. ?: no findings and nothing measured, which is not a pass. A ? can carry (nothing measured yet) or (meter not read).The report.Use --details to see the evidence.

More hero health examples

Example 1. To see the findings

hero health list

Output from version 0.1.36rc13. Trimmed where you see …

Agent health findings · rolling 30d (Oct 07–Nov 06 UTC)
  3 findings, most severe first
  ┌──────────┬─────┬─────────────────────────────────────────┬─────────────────┐
  │ area     │ sev │ finding                                 │ fix             │
  ├──────────┼─────┼─────────────────────────────────────────┼─────────────────┤
  │ Optimize │ MED │ no Core registry push received —        │ hero help route │
  │          │     │ routing on the wheel seed (may miss new │                 │
  │          │     │ models)                                 │                 │
  ├──────────┼─────┼─────────────────────────────────────────┼─────────────────┤
  …
  │ Assure   │ LOW │ no eval baseline — quality unmeasured / │ hero help eval  │
  │          │     │ drifting                                │                 │
  └──────────┴─────┴─────────────────────────────────────────┴─────────────────┘
  nothing measured yet — run your agent through `hero run` to capture your first call, then re-run this command

Findings can appear before any agent work is recorded. On a fresh install of this build, the list held these three.

Example 2. To see every finding

hero health list --all

This prints every finding, not only the first page of 10.

Example 3. To open the report as a page

hero health --html

This command will:

  • Write the report to <HERO_HOME>/report.html (default ~/.hero/report.html), replacing any earlier report there.
  • Open it in your default browser.

The page shows how many areas are failing, the findings table, one card per area with its mark, and the Run: line. Its footer says it holds no prompts or responses and is safe to share. It has no scripts and no web links.

Example 4. To use the read in a script

hero health --json
Field in dataWhat it holds
pillarsEach area's state: failing, attention, ok or unmeasured.
failing_pillarsThe failing areas. Not empty means exit code 1.
govern_postureenforcing, builder, observing or unavailable.
govern_wiredWhether governance acts on your rules on this machine: true, false or null.
findingsEvery finding, uncut, each with skill, bucket, title, impact, unit, severity and fix_action.

--details --json returns the same fields.

Use the exit code to check health in a script: 1 means at least one area is failing.

Exit codes and errors for hero health

CodeMeaningWhat to do
0The output asserts a positive result, or is advice with no verdict.Nothing.
1At least one area is failing, because it carries a high finding.Run the fix for the high finding.
2Refused: unknown flag or subcommand, not configurable, or unavailable.Read the governing_rule line and run the remedy, usually hero health --help.
3A source it needs is unavailable at runtime.Email support at the address in your welcome email, with the output you saw.

A refusal prints refused, reason, governing_rule and remedy lines, or the same four keys with --json.

ReasonCauseFix
unknown_verbAn unknown subcommand, such as hero health bogus.Run hero health --help.
unknown_flagAn unknown flag, or --all on status.Run hero health --help.
not_configurableAn attempt to switch hero health on or off, such as hero health disable.None. Use hero health --details to see the read.
health describe takes only --json (got '<flag>')describe was given another flag.Use hero health describe --json.

Files and environment for hero health

NameKindPurpose
HERO_HOMEEnvironment variableRoot of Agent OS's files on your machine. Default ~/.hero.
HERO_BILLING_RATESEnvironment variablePath to your own rate card. Spend figures use it. Without it, spend is at public list prices. See Use your own rates.
HERO_PROXY_PORTEnvironment variableThe model gateway port the check probes. Default: this install's port, otherwise 8081.
<HERO_HOME>/report.html (default ~/.hero/report.html)File, written by --htmlThe report page. Replaced on each run.

Limits of hero health

LimitBehaviourCan you change it?What to do
WindowEvery figure covers 30 days. There's no option to change the window.NoNone.
Result depends on the machineWith Claude Code or Codex installed, or after hero setup, a model gateway that isn't answering is a high finding, so the command exits 1. On a machine with neither, the same state is a medium finding.NoStart the model gateway with the command in the fix column.
Narrow terminalsThe table fits your terminal width down to a minimum, then runs wider.NoWiden the terminal, or use --json.
Fixes with no commandSome findings name a change to make in your agent, with no hero command to run.NoMake the change the fix column describes.
--htmlOpens a browser on every run. There's no option to write the file without opening it.NoFind the file at the path printed after report →.
Monitor's Health tabIt doesn't yet check that your agents' hooks are installed and approved, and can say your rules hold when the rules file can't be read. Its eval and routing status can disagree with hero eval and hero route. On an Enterprise install with no hook set up, it can say tool calls are checked when they aren't.NoRun hero status to confirm hooks are active, and hero govern status for what is checked. Trust the CLI where they differ.
/hero:health in your agentInstalled by setup.NoRun hero health in your terminal.

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