Ekamyth Agent OS docs
Standard OS / Logs

How observability works

Ekamyth Agent OS records what your agents do, gives you one read of how they're doing, and runs standing checks for you on a cadence, all on your machine.

How does observability work?

Observability is the part of Agent OS that answers "what did my agent actually do, and is anything wrong?" It works from a record of your agents' sessions, kept on your machine, after hero setup.

You use Claude Code or Codex as you normally do. Agent OS records each session: the agent's own tool calls. Standing jobs run checks such as health and eval on a cadence. You read the results with three commands: hero trace for what each session did, hero health for one read with a fix for each finding, and hero schedule for the standing jobs.

Four numbered steps. Your agent works as usual. Agent OS records each session's tool calls. Standing jobs run checks on a cadence. You read hero trace, hero health and hero schedule in your terminal.
The numbers match the steps below. Everything shown is on your machine.

Observability concepts

TermWhat it means
SessionOne run of Claude Code or Codex, from start to finish. The hero trace table also lists Agent OS jobs, which have no agent.
TraceThe record of one session: its tool calls, model calls, refusals, tokens and estimated cost.
ViolationA policy check in a session that didn't pass. hero trace violations lists the newest.
AreaOne of the four groups hero health reports on: Govern, Optimize, Assure and Ledger.
FindingSomething hero health found, with an area, a severity and a fix.
Standing jobA check Agent OS runs for you on a cadence: eval, health, efficiency and codify.
Floor and live cadenceThe floor is the slowest a job may run, which you set. The live cadence is how often it runs now.

The path of a session, step by step

  1. You use your agent as you normally do. hero setup connected Claude Code and Codex to Agent OS.
  2. Agent OS records the session as your agent works: the agent's own tool calls, such as shell commands and edits.
  3. Standing jobs run on a cadence on your machine, as a service that starts at login and restarts after a crash.
  4. You read what happened: hero trace for each session, hero health for the overall read, and hero schedule for when each job ran.

Where you see observability

WhereWhat it shows you
hero traceEach session: tools, model calls, refusals, tokens and estimated cost. Replays one session, and lists violations.
hero healthOne read across Govern, Optimize, Assure and Ledger: spend, findings by area, and a fix for each.
hero scheduleThe standing jobs, their cadence, whether each is on, and when it last ran.
/hero:trace and /hero:health in your agentInstalled by hero setup. Your agent runs the command and explains the result.
hero verdictJob results, which hero trace points to.

How observability decides what to show first

Observability data, and what leaves your machine

DataWhere it's keptContainsLeaves your machine?
Session tracesYour machineEach tool call, which may include its input and command text (hook records redact recognized secrets and limit a target to 200 characters), plus model calls, refusals, tokens and estimated cost.No, by default.
Standing job resultsThe schedule log on your machineOne status line per job runNo
Usage beaconNot sent by hero trace or hero health. Scheduled jobs run through the normal command path, so an eligible job can trigger the beacon check, but each one doesn't send a beacon. The model gateway asks for it when it starts, not on every call it forwards. Whether one is sent depends on whether it is enabled, whether this is an install or upgrade, and the once-a-day limit.A random install id, version, OS family and event. No content.Only where sent. 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.
Health findingsRead from your local records when you run hero healthSpend, calls, and findings by areaNo. Health reads local evidence; it does not upload those findings.

hero health reads its findings from your local records: spend, calls, and findings by area.

A trace record has these fields: trace_id, action, job_id, spans, created_at and execution_identity. Each span has span_id, trace_id, type, actor, name, parent_id, job_id, start, end, status, attributes, fingerprints, boundary_verdict, content_hash and backlog_item_id. The keys inside attributes and fingerprints depend on what recorded the span, so they aren't a closed list. A model-call span records the enrolled agent identity, as agent_identity, and, when Agent OS knows it, the agent session the call belongs to, as session_id.

When part of observability fails

What failsWhat you seeWhat happens to the work
Your trace history passes 64 MBhero trace refuses with exit code 3 and says the history is larger than it can read at once.New sessions are still recorded.
A standing job failshero schedule run marks it ✗ with its first line of output, and exits 1.The other jobs still run.
The schedule service stopshero schedule --service-status shows it.Installed as a service, it restarts after a crash and at login.
Two schedule runs start at onceThe second says another run is in progress, and starts nothing.The first runs the due jobs.

Observability on Claude Code and Codex

Claude CodeCodex
Sessions in hero traceYes, agent claudeYes, agent codex
Standing jobsSame on both. They run on your machine, not inside either agent.

What you can change in observability

SettingDefaultEffect
hero schedule set <skill> <cadence>eval, health and codify daily; efficiency weeklySets a job's floor. See the cadences.
hero schedule on|off <skill>All onSwitches one standing job on or off. An off job stops without a restart.
HERO_HOME~/.heroWhere Agent OS keeps its files on your machine.

See observability for yourself

Run these on your own machine to watch each step.

# Step 2: the sessions Agent OS recorded
hero trace

# Step 3: the standing jobs and when they last ran
hero schedule

# Step 4: one read across your agents
hero health

To read each one line by line, see hero trace, hero health and hero schedule.

Observability limits and next steps

LimitBehaviourWhat to do
Health and your hookshero health doesn't check that your agents' hooks are installed and approved, and can say your rules hold when the rules file can't be read.Run hero status to confirm hooks are active.
Health against hero eval and hero routeHealth's eval and routing status can disagree with those commands, for example Assure ✓ while hero eval gate says there is no baseline.Trust the command.
hero trace exportThe export can include your local session id.Review an export before you share it.

See the limits of hero trace, hero health and hero schedule.

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