Live-tail a run

hiloop runs tail follows a run’s events live, the streaming companion to query. Where a query answers a question about a run after the fact, the tail shows events arriving in real time — point it at a run and watch the model calls, tool calls, and stdio stream in as the agent works.

Watch a run end to end

You need two things: a command to capture, and the run’s id to follow. In one terminal, wrap your agent with hiloop run — it announces the run id on stderr as the run registers:

export HILOOP_API_KEY="hil_…"
export HILOOP_TELEMETRY_ENDPOINT="https://telemetry.hiloop.ai:443"

hiloop run -- claude -p "fix the failing test"
# hiloop: recorded run 01KW42VKWVRK3REQGRM9DSKDW3 — view it with `hiloop runs show 01KW42VKWVRK3REQGRM9DSKDW3`

In a second terminal, follow that run:

export HILOOP_API_KEY="hil_…"

hiloop runs tail 01KW42VKWVRK3REQGRM9DSKDW3

Each event renders as one line, newest last, and the tail keeps running — reconnecting automatically without a fixed attempt limit if the connection drops — until you stop it with Ctrl-C. Pass --no-auto-resume to use only the initial connection:

message=[agent] step 1: working  name=process.stdout  signal=log  run_id=01KW42VKWVRK3REQGRM9DSKDW3  lineage_path=01KW42VKWVRK3REQGRM9DSKDW3  ts=1782548649116224000
message=[agent] step 2: working  name=process.stdout  signal=log  run_id=01KW42VKWVRK3REQGRM9DSKDW3  lineage_path=01KW42VKWVRK3REQGRM9DSKDW3  ts=1782548651145577000
message=[agent] step 3: working  name=process.stdout  signal=log  run_id=01KW42VKWVRK3REQGRM9DSKDW3  lineage_path=01KW42VKWVRK3REQGRM9DSKDW3  ts=1782548653272330000

Events appear as hiloop captures and flushes them. A long-running agent streams progressively; a short command’s events arrive together when it finishes. The tail is read-only and never blocks the run.

Scope what you follow

Narrow the stream to one signal:

# Only model calls
hiloop runs tail "$RUN_ID" --signal llm

JSON output

For piping into jq or another tool, --output json emits each event as one JSON object per line, exactly as received from the live stream:

hiloop runs tail "$RUN_ID" --output json

{"run_id":"01KW42VKWVRK3REQGRM9DSKDW3","lineage_path":"01KW42VKWVRK3REQGRM9DSKDW3","signal":"log","name":"process.stdout","event_id":"01KW42VN4W8Q4E2BYFP8AK4SMP","ts":{"wall_ns":"1782548649116224000","logical":0},"attributes":{"message":"[agent] step 1: working","stream":"stdout","source":"stdio"}}

Live events carry scalar attribute values only. A nested object or array in an event’s attributes — for example a structured annotation payload written with hiloop annotations add --data — is stored in full but omitted from the live stream. Use hiloop query to read the complete stored payload, nested values included.

Resuming after a disconnect

The tail is resumable: every event carries an opaque cursor, and on a dropped connection the client reconnects without a fixed attempt limit and resumes from the last event it saw — no gaps and no duplicates. You don’t have to do anything; a long-lived tail survives network blips and the server’s periodic connection refresh on its own. Use --no-auto-resume when an external supervisor owns the reconnect policy.

Try it without an agent

You can see the whole loop with any command — wrap a shell loop and tail it:

# terminal 1 — capture
hiloop run --verbose -- bash -c 'for i in $(seq 1 5); do echo "[agent] step $i: working"; sleep 2; done'

# terminal 2 — follow (use the run id from terminal 1)
hiloop runs tail "$RUN_ID"

Every line the command prints becomes a log event tagged with the run’s lineage, and it streams straight to your tail.

Live tail vs. query

	When	Use it for
`runs tail`	as events arrive	watching a run unfold, debugging in real time
`hiloop query`	after the fact	precise filters, grouping, aggregation over a finished run

​Watch a run end to end

​Scope what you follow

​JSON output

​Resuming after a disconnect

​Try it without an agent

​Live tail vs. query

Watch a run end to end

Scope what you follow

JSON output

Resuming after a disconnect

Try it without an agent

Live tail vs. query