Ekamyth Agent OS docs
Standard OS / Logs

hero trace

Shows what each agent session did: its tool calls, model calls, refusals, tokens and estimated cost.

What hero trace does

It answers one question: what did my agent actually do? It reports on the sessions recorded on your machine over the last 30 days, with sessions that had problems first. You can replay one session step by step, or list the newest policy violations.

Cost marked ~ is an estimate at public list prices, or at your own rate card when HERO_BILLING_RATES points at one. Runs of hero setup and hero ask are left out of the table.

Synopsis for hero trace

hero trace [status] [--json] [--details]
hero trace list [--all] [--json] [--details]
hero trace show <id> [--json] [--details]
hero trace <id>
hero trace violations
hero trace describe [--json]
hero trace help

Run with no subcommand, it behaves as status. hero trace --all is the same as hero trace list --all.

Subcommands of hero trace

SubcommandWhat it doesReads or changes
statusTotals for the window, then the five sessions that need attention first, with the command to replay the top one. This is the default.Reads
listSessions in the window, newest first: the newest 25, or every retained session with --all.Reads
show <id>Replays one session, trace or job, step by step.Reads
violationsThe newest policy violations, each with its target, rule, reason and id. hero trace violations includes recorded refusals from your rules files; use hero govern for the governance decision and hero enforce for the rule's enforcement state.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 trace.Reads

Arguments for hero trace

Arguments for status and list

ArgumentTypeRequiredDefaultWhat it does
--allFlag, for listNoOff, newest 25Shows every retained session in the window. On its own, hero trace --all runs list --all.
--jsonFlagNoOffMachine-readable output with data and envelope. list --json adds next_cursor, and returns the facts rather than the table.
--detailsFlagNoOffShows every shared number as numerator/denominator, with the reasons a figure is partial.

Arguments for show

ArgumentTypeRequiredDefaultWhat it does
<id>A session, trace or job idYesNoneThe session to replay. Take it from the Run: line or the session column of hero trace, or the id: line of hero trace violations. It matches a session id first, then an exact trace or job id, then a unique prefix of six or more characters. An ambiguous prefix lists up to 10 matching ids. The short form hero trace <id> works only when the id is lowercase hex digits and dashes, at least six characters.
--jsonFlagNoOffThe same steps as machine-readable output, with data and provenance.
--detailsFlagNoOffAdds the raw span list, the line naming the record it read, and the rate card version.

Arguments for violations

None. It lists the newest 20. --json is accepted and ignored.

How hero trace gets its record

Ekamyth Agent OS records each session on your machine as your agent works: its own tool calls. hero trace reads that record, prices model calls against the rate card, and prints the result. For the whole picture, see How observability works.

Your agent works as usual. Agent OS records each session's tool calls on your machine. You read them with hero trace, hero health and hero schedule.
The record is built on your machine as your agent works.

Get started with hero trace

Before you start: Agent OS is installed and you've run hero setup. With no sessions recorded yet, you'll see the first view under Example output.

  1. See your recent sessions.

    hero trace

    You should see the window and a table of sessions, problems first, or a line asking you to use Claude Code or Codex as you normally do.

  2. See every session in the window.

    hero trace list

    You should see the newest 25 sessions, newest first, ending with newest first · replay one: hero trace show <session> · job results: hero verdict.

  3. Check for policy violations.

    hero trace violations

    You should see the newest violations, or a line saying none were recorded. See Example 2.

  4. Replay one session. Use the id the Run: line names.

    hero trace show <id>

    You should see that session's steps in order. See Example 1.

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

Example output of hero trace

Before any sessions are recorded

Example output. The format is the command's; the numbers are examples.

With recorded traces, from sample data

Example output. The format is the command's; the numbers are examples. Sample data: two Agent OS job traces with no model calls, not agent sessions, so session and agent read — and the id in the Run: line is a sample id.

A session with model calls shows its tokens and estimated cost in the last column, and the totals line adds tokens and cost. For Claude Code and Codex sessions, the session column holds the agent's own session id and the agent column says claude or codex; see Example 3. Sessions are told apart by their session id.

How to read hero trace output

LineWhat it meansWhere it comes fromWhat to do
1, 3. WindowThe rolling 30 days the view covers, in UTC.Your local session record.Use hero trace list --all to show all sessions read within the 30-day window, or hero trace show <id> to replay an older session still in the trace store.
2. No sessions yetNo session has been recorded in the window.Your local session record.Use Claude Code or Codex, then run this again.
4. TotalsSessions, tool calls, model calls, failed and refused steps in the window. Held, blocked, flagged, asked-you, tokens and cost are added only when they aren't zero.Your local session record, priced on the rate card.If a count of problems isn't zero, replay the session the Run: line names.
5. Table headerOne row per session.Your local session record.No action is required for the table header; it labels the session details below.
6. A sessionwhen: when the session started, MM-DD HH:MM. A longer session can show its start and end, such as 11-06 00:00–01:58. session: the agent's own session id, or — for a job with none. agent: the agent that ran it, or —, followed by its Agent OS identity in short form, such as agp_4007…89cc, or id not recorded, no id enrolled or id unreadable. steps: tool calls with their names, and model calls. outcome: ✓ ok when Agent OS recorded no failure, refusal, hold, block or flag; otherwise the count, such as ✗ 1 failed. tokens · cost: from the session's model calls, or — no model calls.Your local session record.Replay it with hero trace show <id>.
7. RunThe first session worth opening. Shown by status only.The report.Run it.
8. FooterHow many sessions are shown, in what order, and the commands for all sessions, one replay and job results.The report.Use hero trace list for more sessions.

More hero trace examples

Example 1. To replay one session

hero trace show <id>

Sample output (simulated data). hero trace show claude-3cd63, a Claude Code session with one model call and one tool call. Lines are left out where you see …

  TRACE  session=claude-3cd63  ·  2 step(s)  ·  ✓ OK  ·  2026-11-08 14:23:06 UTC
  ───────────────────────────────────────────────────────────────────────────
  session  claude-3cd63
  agent    identity not recorded
  harness  claude
  actor proxy  ·  model claude-sonnet-5  ·  elapsed 25.55s

  step  t+            dur  stage    recorded
     1  +0.000s    25.55s  request  provider anthropic
     1  +0.000s            route    model claude-sonnet-5 · class code
     1  +0.000s            govern   ✓ allow · rule not attributed
     2  +0.000s    40.0ms  tool     agent:Bash ran
  …
     1  +0.000s    25.55s  outcome  ✓ ok · surface claude
     2  +0.000s    40.0ms  outcome  ✓ ok · surface claude · agent:Bash

  action allowed yes
  task completed unknown · task verified unverified
  batch attested no
  …

  1 tool call(s)  —  All clean.
  …

The header names the session, then three lines say who ran it: session, the agent session id; agent, the full Agent OS identity of the agent (agp_ and 32 hex characters), or no agent identity enrolled (hero identity enroll), agent identity could not be read when recorded or identity not recorded; and harness, claude or codex. Each step shows its stage: the model request, the route it took, the governance decision, the tool call and the outcome, with the agent named on the outcome lines, such as surface claude. task completed and task verified are about the job, which hero verdict checks; they're separate from whether each step ran. On the route line, the decision is in words, such as kept the requested model, cheapest model that fits or routing off, and on the request line the credential reads, for example, your own signed-in subscription or your own API key.

Add --details to also print the raw span list, the line naming the record it read and the rate card version. Without it, a session with priced model calls ends with a prices: line naming the price basis.

If the id isn't found, it refuses with exit code 2. See the error.

Example 2. To see policy violations

hero trace violations

Example output. The format is the command's. Before any policy checks are recorded.

trace violations — none recorded — unavailable: no policy-checked traces observed yet (no verdict)

This means no policy check has run, not that everything passed. With no session record at all, it prints trace violations — none recorded — unavailable: no trace store yet, nothing observed (no verdict).

Output from version 0.1.36rc13, from a home with sample data. Trimmed where you see …

trace violations — newest 15 policy violation(s)

  ✗  2026-11-07T00:04:28Z  anthropic/claude-sonnet-5
       id: demo-seed-ba588b3ff1834ee424e16828

  ✗  2026-11-06T08:29:34Z  anthropic/claude-sonnet-5
       id: demo-seed-d655d68a1410b27652ca1d33
  …

Each violation shows when it happened, the model, and an id.

Example 3. To see every session

hero trace list

It prints the same table as the default view, titled Trace · every session · rolling 30d, newest first, with no Run: line. Before any sessions are recorded, it prints that title and the same line as the default view. Add --all for every retained session. With more than 25 sessions in the window, the title reads Trace · newest 25 sessions and the footer names hero trace list --all.

Sample output (simulated data). Claude Code and Codex sessions over 30 days. Lines are left out where you see …

Trace · newest 25 sessions · rolling 30d (Oct 09–Nov 08 UTC)
  …
  ┌───────────────────┬──────────────┬────────┬──────────────────────────┬────────────┬────────────┐
  │ when (UTC)        │ session      │ agent  │ steps                    │ outcome    │ tokens ·   │
  │                   │              │        │                          │            │ cost       │
  ├───────────────────┼──────────────┼────────┼──────────────────────────┼────────────┼────────────┤
  │ 11-08 14:23       │ claude-3cd63 │ claude │ 1 tool (Bash) · 1 model  │ ✓ ok       │ 20,200 ·   │
  …
  ├───────────────────┼──────────────┼────────┼──────────────────────────┼────────────┼────────────┤
  │ 11-08 10:38–11:26 │ codex-3cd61  │ codex  │ 5 tools (Read, Grep,     │ ✓ ok       │ 9,335 ·    │
  …
  ├───────────────────┼──────────────┼────────┼──────────────────────────┼────────────┼────────────┤
  │ 11-07 06:11–06:53 │ claude-3cd53 │ claude │ 11 tools (Edit, Grep,    │ ✗ 1        │ 17,197 ·   │
  …
  └───────────────────┴──────────────┴────────┴──────────────────────────┴────────────┴────────────┘
  14 problems not shown above · hero trace violations
  newest 25 of 70 sessions · all: hero trace list --all · replay one: hero trace show <session> · ~
    means estimated at public API list prices · job results: hero verdict

Each row is one session. session is the agent's own session id, which you pass to hero trace show, and agent is the agent that ran it, claude or codex, with its Agent OS identity in short form.

Example 4. To use the record in a script

hero trace --json

Its data holds headline, sessions, sessions_selected, last_verdict and next_step, then agent_sessions, one entry per session with its tools, model calls, problem counts, tokens and cost, and jobs, one entry per job with its outcome.

Exit codes and errors for hero trace

CodeMeaningWhat to do
0The output asserts a positive result, or is advice with no verdict. The empty state exits 0.Nothing.
1A truthful negative result.Read the output.
2Refused: unknown flag or subcommand, not configurable, a missing or unknown id for show, or an unreadable record for violations.Read the reason and governing_rule lines. See the errors below.
3A source it needs is unavailable at runtime, such as a damaged session record for status, list or show.See the errors.

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

ErrorCauseFix
trace has no verb '<word>'An unknown subcommand. Also printed for the short form when the id isn't lowercase hex and dashes, such as hero trace trace-2.Use hero trace show <id>.
trace has no flag '<flag>'An unknown flag.Check the synopsis.
trace is not configurableAn attempt to switch hero trace on or off.None. Recording needs no setting.
trace show needs <trace_id>show was run without an id.Add an id from hero trace.
no trace or job '<id>' in the trace ledgerNo session, trace or job has that id.Run hero trace list and copy an id.
no trace or job '<id>' — no trace ledger yetNo session has been recorded on this machine.Use Claude Code or Codex, then try again.
'<prefix>' matches more than one trace or job — pass a full id: <id>, <id>The prefix matches several ids.Pass one of the full ids listed.
<file> is present but cannot be readThe session record on your machine is damaged. Exit code 3.Email support at the address in your welcome email.
trace_corrupt — Trace source degraded; no content was readThe same damage, met by violations. Exit code 2.Email support at the address in your welcome email.
Your trace history is larger than this build can read at once (over 64 MB). Recent traces are still recorded; large-history reading is coming.The session history on your machine is over 64 MB. Exit code 3.There is no supported fix for this. Recent traces are still recorded.

Files and environment for hero trace

NameKindPurpose
HERO_HOMEEnvironment variableRoot of Agent OS's files on your machine, including the session record. Default ~/.hero.
HERO_BILLING_RATESEnvironment variablePath to your own rate card. Cost figures use it. Without it, cost is at public list prices. See Use your own rates.

Limits of hero trace

LimitBehaviourCan you change it?What to do
WindowThe table and --details cover 30 days. show reaches any retained trace.NoUse hero trace show <id> to replay an older session still in the trace store.
Rows in listThe newest 25, unless you add --all.YesUse hero trace list --all.
Large trace historyOver 64 MB, hero trace refuses with exit code 3. New sessions are still recorded.NoThere is no supported fix for this. Recent traces are still recorded.
Real sessionsTool calls are recorded as your agent works.NoSee which model served each call in hero route.
Failures and violationsviolations lists policy violations only, not failed steps. A session that failed can point you to violations, which then finds nothing.NoReplay the session with hero trace show <id>.
Short formhero trace <id> works only for ids made of lowercase hex digits and dashes.NoUse hero trace show <id>.

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