Ekamyth Agent OS docs
Added for agents / Gets smarter

hero ask

Answers a question about your agents' recorded work, such as which job failed or which models did the work, and names the records behind the answer.

What hero ask does

It answers questions in your own words from what Ekamyth Agent OS recorded on your machine. Six kinds of question are answered from your local records, with no model call: your last session, failed jobs, whether any job touched something you name, which models did the work and what it cost, which rules are checked as code, and what's waiting for your approval. Any other question goes to your agent's active model through the model gateway, with a summary of your local records.

Synopsis for hero ask

hero ask "<question>"
hero ask

Every word after ask is read as the question, so quotes are optional unless your shell would read a character such as ? or ' itself. To name a thing for a search, put it in quotes inside the question, such as hero ask 'did any job touch "prod.db"?', or put it right after the verb, as in hero ask did any job touch prod.db.

Subcommands of hero ask

None. hero ask takes a question, not subcommands.

Arguments for hero ask

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
<question>TextNoNone: with no question it prints ask me about failed jobs, model usage, costs, rules, or pending approvals.Any textThe question. See Questions it answers locally.

Questions it answers locally

hero ask matches your question against these, in this order, and answers the first that fits.

Ask aboutIt matches words such asIt answers from
Your last sessionlast session, latest session, previous sessionYour session history
Failed jobsfail, error, broke, crashYour session history
Whether a job touched somethingdid, what, who or has, then do, touch, call, run, write, delete, send or use, with the thing in quotes or right after the verbYour session history, up to eight matches
Models and costmodel, rout, which llm, cost, spend, spent, expensive, billYour record of model calls
Rulesrule, rules, promot, enforce, code, gatekeepYour registered rules
Waiting for approvalpending, approval, inbox, heldhero inbox

For models and cost, it reads a time window from the question: today, yesterday, last <n> days or past <n> days, and this week, last week or past week (the last 7 days). Without one, it uses the last 30 days and says so. A window phrase it can't read, such as last month, is named in the answer, which uses the last 30 days instead.

How hero ask gets its answer

  1. Local first. If the question matches one of the six kinds above, the answer is made on your machine from your local records, and your question isn't sent anywhere.
  2. Your agent's active model next. Otherwise, if the model gateway is running, hero ask sends your question to the active model through the model gateway, with a summary of your local records: your 20 most recent jobs with their status and ids, failed job ids, model calls and cost by model, the ids of rules checked as code and counts of the rest, and your pending approvals. The model is told to answer only from that data. The call goes to your provider like any call through the model gateway, and is recorded and costed like one. The active model is the one your model gateway's route settings name, or else the one your Ekamyth Portal last used, sent through the local model gateway. If there's no usable active model or the gateway isn't running, hero ask falls back to the local answer. It never silently picks a default model.
  3. Receipts come only from your history. Job ids a model's answer names become receipts only when they exist in your history.
  4. Receipts are re-checked. Before the answer prints, every receipt is looked up again, and any that no longer resolves is removed, with a note.
  5. The question is recorded. Each question is recorded as a job, which hero verdict counts, and as a short record in your session history, holding the kind of question, the stores it read, the receipts and the answer's length. The first 200 characters of your question are kept on your machine as the job's goal. They aren't sent to Ekamyth.

If the model gateway isn't running, or the model can't answer, the answer starts Model answer unavailable and gives the local answer instead.

Get started with hero ask

Before you start: Agent OS is installed, hero setup has run, and you've used Claude Code or Codex since. These commands work the same on Mac and Linux. All three are answered locally.

  1. Ask which job failed.

    hero ask "which job failed?"

    You should see no failed jobs in the ledger., or a count of failed jobs, one line each with its id, then a receipts: line.

  2. Ask which models did the work this week.

    hero ask "which models did the work this week?"

    You should see last 7 days: with the number of calls and the total cost, then one line per model. With no calls, it says last 7 days: no metered calls.

  3. Ask what's waiting for you.

    hero ask "what's pending approval?"

    You should see nothing pending., or a count and one line per held action, with its stakes, id, action and target.

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

How to read hero ask output

PartWhat it meansWhat to do
The answerThe local answer, or the model's answer in one short paragraph.For the full view, run the command named in What it does.
Model answer unavailable — local proxy is not running.The question needed a model, and the model gateway isn't running. A local answer follows.Start the model gateway with hero proxy, or ask one of the local questions.
Model answer unavailable. Local receipts only:The model gateway is running, but the model couldn't answer. A local answer follows.Ask again, or ask one of the local questions.
not captured / can't answer that yetNeither a local answer nor a model answer was found. It lists questions it can answer.Ask one of those.
receipts:The records behind the answer, such as job ids, then (drill: hero trace show <id>). The last receipt, recorded:ask-<id>, is this question's own record.Run the hero trace show command it names.
(audit: <n> receipt(s) no longer resolve and were stripped)Some records the answer named no longer exist, and were removed from the receipts.Treat the answer with care.

More hero ask examples

Example 1. To find the jobs that touched a file

hero ask 'did any job touch "prod.db"?'

This lists up to eight matching steps, each with its actor, step, type, job and id. With no match it says it searched step names, actors, fingerprints and job actions, and that commands inside steps aren't searched.

Example 2. To see which rules are checked as code

hero ask "what rules are code?"

This prints how many rules are checked as code out of all your rules, one line each, then the rules that could be, and the rules a model checks. With no rule registry on this machine, it says no rule registry yet.

Exit codes and errors for hero ask

CodeMeaning for this commandCauseWhat to do
0An answer printedAny answer, including "not captured" and "Model answer unavailable".Read the answer.

Because every answer exits 0, a script can't tell from the exit code whether a question was answered.

Files and environment for hero ask

NameKindPurpose
HERO_HOMEEnvironment variableRoot of the records hero ask reads. Default ~/.hero.

Limits of hero ask

LimitBehaviourCan you change it?What to do
Name in helpask and inbox are two separate commands, not two names for one. hero ask answers questions over your captured records; hero inbox lists held actions. hero help doesn't list ask.NoUse each by its own name. Use this page for hero ask.
Questions answered by a modelYour question and a summary of your local records, including the ids of rules checked as code and your pending approvals, go to your provider through the model gateway.Yes: ask one of the local questionsSee Questions it answers locally.
Naming a thingA question about whether a job touched something needs the thing in quotes, or right after the verb, such as touch prod.db. If it finds neither, it asks you to name it.NoPut the name in quotes.
Time windowsOnly today, yesterday, last <n> days or past <n> days, and this week, last week or past week are read, for models and cost. Anything else uses the last 30 days.NoUse one of those phrases.
Answer lengthA model's answer is one short paragraph.NoAsk a narrower question.
Exit codeEvery answer exits 0.NoRead the answer text.

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