hero status
Checks that Ekamyth Agent OS is installed, active and connected to your agents, and names one next step when something's wrong.
What hero status does
It answers one question: is Agent OS set up and healthy on this machine, and if not, what do I do next? It runs eight checks in a fixed order, prints a ✓ or ✗ for each, and names the one step to take.
- Use it when you've just installed or upgraded, something stopped working, or you want to confirm your agents are connected.
- Use something else when you want each agent's connection in detail (
hero setup --check) or how your agent is doing overall (hero health). - Reads or changes: it reads, and can send the anonymous usage beacon (see Files and environment). It never creates
~/.hero, and it never runs the step it prints.
Synopsis for hero status
hero status [--details] [--json]
hero status --help
-h, hero status help and hero help status print the same help.
Subcommands of hero status
None. hero status takes no subcommand. The commands that used to sit under it are under hero codify, and a word after status is refused with a pointer there.
Arguments for hero status
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--details | Flag | No | Off | Adds an evidence: block under the table, with one line per check showing what it found: paths, ports and sizes. Ignored with --json, which always carries this detail. | |
--json | Flag | No | Off | Prints one JSON object instead of the table. See Example 2. | |
--help, -h | Flag | No | Off | Prints the help. It works only as the only argument. |
How hero status checks your install
Each check reads the current state from the part of Agent OS that owns it, every time you run the command. If one check can't run, it shows could not be checked, and the other seven still run.
| Check | What it asks |
|---|---|
install | Which version is installed. It's always ✓. |
access | Is this machine active? |
proxy | Does the model gateway your agents use answer, and does it belong to this install? |
agents | Are Claude Code and Codex installed, and are their settings pointed at the model gateway? |
hooks | Are the Agent OS hooks in each agent, and has Codex approved them? |
enforcement | Can one of your rules block a tool call right now? |
stores | Can Agent OS read its own data on this machine, and is any of it damaged? |
disk | Is there at least 5 GB free where Agent OS keeps its data? |
Under the table, a rules line counts your registered rules and how many block. Then it prints one next step: the step of the first ✗ check, in table order. The proxy check makes one request to the model gateway on your machine. It doesn't make a model call, so a ✓ doesn't test your provider credentials. The agents check reads your agents' settings; it doesn't watch a running session.
Get started with hero status
Before you start: Agent OS is installed. Nothing here changes anything, so there's nothing to undo.
Run the eight checks.
hero statusOn a connected machine you should see
8 checks · all ok, and it exits0. Otherwise you see which checks need attention, and anext:line.If there's a
next:line, run that command, then runhero statusagain.Each fix can reveal the next ✗. Repeat until all eight are ✓.
See what each check found.
hero status --detailsYou should see the same table, then an
evidence:line per check.
Example output of hero status
Before setup
Output from version 0.1.36rc13. Trimmed where you see …
On a connected machine
Output from version 0.1.36rc13. Trimmed where you see …
status — Ekamyth on this machine
8 checks · all ok
┌───┬───────────────┬────────────────────────────────────────────────────┐
│ │ check │ state │
├───┼───────────────┼────────────────────────────────────────────────────┤
│ ✓ │ install │ ekamyth 0.1.36rc13 (build 1c14e25f63a7) │
│ ✓ │ access │ active │
│ ✓ │ proxy │ running │
│ ✓ │ agents │ Claude Code, Codex route through the proxy │
│ ✓ │ hooks │ installed and approved │
│ ✓ │ enforcement │ armed │
│ ✓ │ stores │ readable │
│ ✓ │ disk │ enough free space · stores within limits │
└───┴───────────────┴────────────────────────────────────────────────────┘
rules 0 registered · 0 blocked
paths, ports and sizes: hero status --details
How to read hero status output
| Line | What it means | What a ✗ can say, and the next step |
|---|---|---|
| 1. Title | Fixed text. | |
| 2. Summary | How many checks passed, and how many need attention. 8 checks · all ok when every check passes and every registered rule blocks. 8 checks ok · <m> of <n> rules blocked when checks pass but some rules don't block. | Follow the next: line. |
3. install | The installed version. Same as hero version. | Always ✓. |
4. access | Whether this machine is active. Until it is, nothing is connected. | not active on this machine: hero setup. See Activation. |
5. proxy | Whether the model gateway your agents use answers, and belongs to this install. | not running: hero proxy --install-service && hero setup. your agents' proxy is not answering: hero proxy --port <port>. another Ekamyth install answers on its port or something that is not the proxy answers on its port: hero status --details. running · upstream failing for <model>: your provider is failing for that model. not checked — your agents' proxy is remote: check the model gateway at the address it names. |
6. agents | Which agents are installed, and whether each one's settings point at the model gateway. | <names> not routed through the proxy: hero setup. no Claude Code or Codex found: install one, then run hero setup. |
7. hooks | Whether each agent has the Agent OS hooks, and Codex has approved them. | not installed: hero setup. Codex hooks not approved yet: approve them in Codex's hook review, or run hero setup again once Codex runs. If Codex's hooks feature is off, the step is codex features enable hooks. |
8. enforcement | Whether your rules can block a tool call now. | not armed — no rule can block a tool call: hero codify enforce on. turned off by <VAR>=<value>: an environment setting turned it off. The step unsets it. |
9. stores | Whether Agent OS can read its own data. nothing recorded yet is normal before your first session. | The state names what can't be read, and the step says how to fix it, such as a chmod command. Status never runs it for you. |
10. disk | Whether at least 5 GB is free where Agent OS keeps its data. | less than 5 GB free: free at least 5 GB on that disk. |
11. rules | How many rules are registered, and how many of them block. rules cannot be read when the count can't be read. | When every check passes but a rule doesn't block, the next step is hero codify. |
12. next: | The one step to take: the first ✗ check's. It's absent when nothing is due. | Run it, then run hero status again. |
| 13. Last line | Where to see the evidence. | hero status --details. |
More hero status examples
Example 1. To see the evidence behind each check
hero status --details
It prints the same table, then one evidence: line per check: the version's location, the model gateway's address and what answered there, each agent's settings file and value, the hook counts such as wired 5/5, the enforcement switches and the free space. The evidence holds full paths and ports, so remove them before you paste it anywhere public.
Example 2. To use the checks in a script
hero status --json
Example output. The format is the command's; the numbers are examples.
Excerpt: detail values and later checks cut with ….
{"schema": "hero.status.v1", "checks": [{"id": "install", "ok": true, "state": "ekamyth 0.1.36rc13", "detail": "…"}, {"id": "access", "ok": false, "state": "not active on this machine", "detail": "…"}, …], "rules": {"registered": 0, "blocked": 0}, "next_step": "hero setup", "exit_code": 1}
| Field | Meaning |
|---|---|
schema | Always hero.status.v1. |
checks | Eight objects, in table order. |
checks[].id | install, access, proxy, agents, hooks, enforcement, stores or disk. |
checks[].ok | true for a pass, and also for a store that wasn't checked. Read state to tell them apart. |
checks[].state | The text in the table. |
checks[].detail | The --details evidence line. It holds full paths and ports. |
rules.registered, rules.blocked | The rule counts, or null when they can't be read. |
next_step | The one next step, or null. |
exit_code | The exit code: 0 or 1. |
In a script, read exit_code or checks. Exit code 1 means something needs attention, not that the command failed.
Example 3. To see why enforcement reads off
HERO_CODIFY_ENFORCE=0 hero status | grep enforcement
Example output. The format is the command's; the numbers are examples.
│ ✗ │ enforcement │ turned off by HERO_CODIFY_ENFORCE=0 │
The state names the setting that turned enforcement off. The next step is unset HERO_CODIFY_ENFORCE.
Exit codes and errors for hero status
| Code | Meaning | What to do |
|---|---|---|
0 | Every check passed, and the rule counts could be read. Also help. | Nothing. |
1 | A check needs attention, or the rule counts can't be read. The full report is still printed. | Run the next: step. |
2 | Refused: a word or option hero status doesn't take. | Use only --details and --json. |
A refused word, for example hero status list:
refused status has no verb 'list'
reason unknown_verb
governing_rule hero status takes no verb — the rule dashboard's verbs belong to hero codify
remedy hero codify list
A refused option, for example hero status --bogus:
refused status has no flag '--bogus'
reason unknown_flag
governing_rule hero status takes no verb and only the flags --details, --json
remedy hero status --help
With --json, a refusal is one object with refused, reason, governing_rule and remedy.
Files and environment for hero status
Status changes none of your settings. It can send the anonymous usage beacon: a random installation id, the version, the platform and the event. 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.
| Name | Kind | Purpose |
|---|---|---|
~/.claude/settings.json | Your Claude Code settings, read | The agents and hooks checks. |
~/.codex/config.toml, ~/.codex/hooks.json | Your Codex settings, read | The agents and hooks checks. |
HERO_HOME | Environment variable | Where Agent OS keeps its data. Default ~/.hero. |
HERO_PROXY_PORT | Environment variable | The model gateway port checked when setup recorded none. |
HERO_CODIFY_ENFORCE | Environment variable | 0, off, false or no turns enforcement off, and the enforcement row says so. |
HERO_BEACON=off | Environment variable | Turns off the anonymous usage beacon, which hero status can send. |
Limits of hero status
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| Exit code before setup | Until hero setup and the model gateway have run, several checks are ✗ and the exit code is 1. | No | In scripts, read exit_code and checks from --json. |
| One step at a time | next: names only the first ✗ check's step. | No | Run it and check again, or read --details. |
| Credentials | The proxy check doesn't make a model call, so it doesn't test your key or sign-in. | No | Use your agent, then check hero efficiency for recorded calls. |
| A model gateway on another machine | It isn't checked. The proxy row reads not checked, and the exit code is 1. | No | Check that model gateway where it runs. |
| Agents | Only Claude Code and Codex are checked. | No | None. |
| Help | hero status --help prints a one-line summary, and works only as the only argument. | No | Use this page. |
| Paths in the output | --details and --json include full paths and ports. | No | Remove them before you share the output. |
| Table width | The state something that is not the proxy answers on its port is one character wider than its column, so that row's border shifts. | No | None. |
Commands related to hero status
proxy row checks.
hero codifyYour rules, and turning enforcement on.
hero healthHow your agent is doing, beyond the install.
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.