Skip to main content
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: 
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. 
agentdbg view --port 9000 --no-browser
Press Ctrl+C in the terminal to stop the server. See the CLI reference for the full option list.

​
UI layout

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)
  • 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:
ChipEvents shown
AllEvery event in the run
LLMLLM_CALL events
ToolsTOOL_CALL events
ErrorsERROR events
StateSTATE_UPDATE events
LoopsLOOP_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.
ParameterDescription
run or run_idRun to open. Accepts a full UUID or a short prefix.
filterActive event filter: all, llm, tools, errors, state, or loops.
poll_runsHow often (in seconds) to refresh the run list. Default 3, range 1–60.
poll_eventsHow 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.