> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Live-tail a run

> Follow a run's telemetry as it happens — events stream to your terminal the moment they're captured.

`hiloop runs tail` follows a run's events **live**, the streaming companion to
[`query`](/observability/query-telemetry). 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`](/guides/capturing-telemetry) — it announces the **run id** on stderr as
the run registers:

```sh theme={null}
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:

```sh theme={null}
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:

```text theme={null}
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
```

<Note>
  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.
</Note>

## Scope what you follow

Narrow the stream to one [signal](/observability/event-model):

```sh theme={null}
# 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:

```sh theme={null}
hiloop runs tail "$RUN_ID" --output json
```

```json theme={null}
{"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"}}
```

<Note>
  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`](/observability/query-telemetry) to read the complete stored payload,
  nested values included.
</Note>

## 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:

```sh theme={null}
# 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`](/observability/query-telemetry)** | after the fact   | precise filters, grouping, aggregation over a finished run |