> ## Documentation Index
> Fetch the complete documentation index at: https://refinehq.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Using the AgentDbg Timeline Viewer to Inspect Runs
> The AgentDbg timeline viewer shows every run event in your browser. Navigate, filter, rename, and delete runs directly from the local UI—no cloud required.
The AgentDbg timeline viewer is a browser-based UI that lets you inspect agent runs without leaving your machine. It is served entirely from your local disk — there is no cloud component, no login, and no data sent anywhere. You start it with `agentdbg view`, and it stays running so that new runs appear automatically as your agent executes.
## Starting the viewer
Run the following command in your terminal:
```bash theme={null}
agentdbg view
```
This starts a local HTTP server and opens your default browser. By default the viewer is available at:
```
http://127.0.0.1:8712
```
You can change the host and port with `--host` and `--port`. To start the server without opening a browser (for example in an SSH session), add `--no-browser`.
```bash theme={null}
agentdbg view --port 9000 --no-browser
```
Press **Ctrl+C** in the terminal to stop the server. See the [CLI reference](/docs/reference/cli) for the full option list.
***
## UI layout
### Sidebar — run list
The left sidebar shows your recent runs, newest first. Each row displays:
* **Run name** — a label you can set or edit
* **Started time** — when the run began (UTC)
* **Status** — `ok`, `error`, or `running`
* **Duration** — total elapsed time in milliseconds
A pulsing indicator marks runs that are still **running**. Click any row to load that run in the main panel.
### Run summary panel
When you select a run, the main area shows a summary at the top with:
* **Status badge** — `OK` (green), `ERROR` (red), or `RUNNING` (animated)
* **KPI counts** — LLM calls, tool calls, errors, and loop warnings
* **Filter chips** — quickly narrow the event list (see [Filtering events](#filtering-events))
* **Jump to first error** — a shortcut button that scrolls the timeline to the first `ERROR` event when one exists
### Timeline
Below the summary, events are listed in chronological order. Click any event row to expand it and see the full `payload` and `meta` objects as formatted JSON.
Expanding an LLM call shows the model name, prompt, response, token usage (`prompt_tokens`, `completion_tokens`, `total_tokens`), provider, temperature, stop reason, and status. If the call failed, an `error` object is shown with the exception type, message, and stack trace.
Expanding a tool call shows the tool name, input `args`, `result`, and status. Error details are shown when `status` is `error`.
Error events show `error_type`, `message`, and `stack`. Guardrail aborts also include `guardrail`, `threshold`, and `actual` fields so you can see exactly which limit was hit.
Loop warnings show the repeated `pattern`, number of `repetitions`, and the `evidence_event_ids` that were involved in the detected loop.
State updates show the full `state` snapshot and an optional `diff` object if your agent computed one.
***
## Filtering events
Use the filter chips in the run summary panel to show only specific event types. The available filters are:
| Chip | Events shown |
| ---------- | ---------------------- |
| **All** | Every event in the run |
| **LLM** | `LLM_CALL` events |
| **Tools** | `TOOL_CALL` events |
| **Errors** | `ERROR` events |
| **State** | `STATE_UPDATE` events |
| **Loops** | `LOOP_WARNING` events |
The active filter is reflected in the page URL so you can bookmark or share a filtered view.
***
## URL parameters
You can control the viewer's initial state with URL parameters. The UI keeps these in sync as you interact, so the URL always reflects what you are viewing.
| Parameter | Description |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `run` or `run_id` | Run to open. Accepts a full UUID or a short prefix. |
| `filter` | Active event filter: `all`, `llm`, `tools`, `errors`, `state`, or `loops`. |
| `poll_runs` | How often (in seconds) to refresh the run list. Default `3`, range 1–60. |
| `poll_events` | How often (in seconds) to poll for new events on a running agent. Default `2`, range 1–60. |
**Examples:**
```
http://127.0.0.1:8712/?run=a1b2c3d4
http://127.0.0.1:8712/?run_id=a1b2c3d4-1234-5678-90ab-cdef12345678&filter=errors
http://127.0.0.1:8712/?poll_runs=5&poll_events=3
```
***
## Renaming runs
To rename a run, click the **rename** button next to the run name in the summary panel. Type a new name and confirm. This writes the updated `run_name` to the run's `run.json` file on disk. The sidebar reflects the new name on the next poll (within a few seconds).
***
## Deleting runs
To delete a run, click the **delete** button in the run summary panel and confirm the prompt. The run directory and all its contents (`run.json` and `events.jsonl`) are permanently removed from disk. The sidebar automatically switches to another run, or shows "No runs yet" if no other runs exist.
Deletion is permanent. AgentDbg removes the run directory from disk and there is no undo. Make sure to export the run first if you need to keep a copy.
***
## Live refresh
The viewer automatically stays up to date while your agents are running:
* **Run list** is polled every \~3 seconds (configurable with `poll_runs`). New runs appear in the sidebar without a page reload. Runs that are deleted from disk are removed on the next poll.
* **Event list** is polled every \~2 seconds (configurable with `poll_events`) while the selected run has `status: running`. The timeline and summary update in place. Polling stops automatically once the run reaches `ok` or `error`.
* **Polling pauses** when you switch away from the browser tab (using the Page Visibility API) and resumes the moment you switch back.
You can leave `agentdbg view` running all day. Every run your agent produces will appear in the sidebar in real time.