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.
- Use it when you want a quick answer without knowing which command holds it.
- Use something else when you want the full view: job results (
hero verdict), a session step by step (hero trace), cost (hero efficiency), rules (hero enforce) or held actions (hero inbox). - In help:
hero helpdoesn't listhero askas its own command. See Limits. - Reads or changes: it reads your records and changes none of your work. It records each question as a job and adds a short record of it to your session history. A question it can't answer locally is sent to your provider; see How it gets its answer.
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
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
<question> | Text | No | None: with no question it prints ask me about failed jobs, model usage, costs, rules, or pending approvals. | Any text | The 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 about | It matches words such as | It answers from |
|---|---|---|
| Your last session | last session, latest session, previous session | Your session history |
| Failed jobs | fail, error, broke, crash | Your session history |
| Whether a job touched something | did, what, who or has, then do, touch, call, run, write, delete, send or use, with the thing in quotes or right after the verb | Your session history, up to eight matches |
| Models and cost | model, rout, which llm, cost, spend, spent, expensive, bill | Your record of model calls |
| Rules | rule, rules, promot, enforce, code, gatekeep | Your registered rules |
| Waiting for approval | pending, approval, inbox, held | hero 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
- 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.
- Your agent's active model next. Otherwise, if the model gateway is running,
hero asksends 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 askfalls back to the local answer. It never silently picks a default model. - Receipts come only from your history. Job ids a model's answer names become receipts only when they exist in your history.
- 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.
- The question is recorded. Each question is recorded as a job, which
hero verdictcounts, 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.
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 areceipts:line.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 sayslast 7 days: no metered calls.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
| Part | What it means | What to do |
|---|---|---|
| The answer | The 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 yet | Neither 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
| Code | Meaning for this command | Cause | What to do |
|---|---|---|---|
0 | An answer printed | Any 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
| Name | Kind | Purpose |
|---|---|---|
HERO_HOME | Environment variable | Root of the records hero ask reads. Default ~/.hero. |
Limits of hero ask
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| Name in help | ask 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. | No | Use each by its own name. Use this page for hero ask. |
| Questions answered by a model | Your 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 questions | See Questions it answers locally. |
| Search depth | A search for a thing looks at step names, actors, fingerprints and job actions. Commands inside steps aren't searched. | No | Use hero trace show <id> to read a step's detail. |
| Naming a thing | A 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. | No | Put the name in quotes. |
| Time windows | Only 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. | No | Use one of those phrases. |
| Answer length | A model's answer is one short paragraph. | No | Ask a narrower question. |
| Exit code | Every answer exits 0. | No | Read the answer text. |
Commands related to hero ask
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.