Screens / Watching the work

Trace viewer

Show what happened in a run in order: which step called which tool, how long each took, and where it broke.

For: Engineers and ops people finding out why a run went wrong.

Markdown

3 ways to lay it out

1. Timeline alone

Pick it when: Embedded in a run page: a wide strip that opens on the first failure.

Rows of nested spans as bars on a shared clock, the failing one solid and the ones after it pale.

Trace viewerProEach span as a bar on a shared clock, nested under its parent, opening on the first failure.
Run receiptProWhat the run cost.

Install timeline alone

Pro and Premium items need a licence key; free ones install as they are.

2. Timeline with a span panel

Pick it when: People click into a span to read its input, output and error.

The timeline on the left and the selected span's detail on the right.

Trace viewerProThe timeline.
PayloadFreeCode or query text the agent ran, shown as a block.
Log streamProThe log lines from that span.

Install timeline with a span panel

Pro and Premium items need a licence key; free ones install as they are.

3. Who handed off to whom, first

Pick it when: Multi-agent runs, where the first question is which agent did this.

A tree of agents on the left and the timeline of the selected agent's spans on the right.

Run treeProThe orchestrator and the specialists it handed work to.
Trace viewerProThe selected agent's spans.
Agent avatarFreeTells the agents apart at a glance.

Install who handed off to whom, first

Pro and Premium items need a licence key; free ones install as they are.

Rules that matter most here

Unknown stays unknown
A span still running stretches to now and has no duration; a missing span is a gap, not a guess.
Motion never says something false
The span that broke is solid, the ones that failed because of it are pale, and nothing animates after the outcome.
Reasoning is believed, not verified
A span's reasoning text is the agent's account, labelled as such.

Already covered elsewhere

Pattern: Agent trace viewer for React

Brief for a coding agent

Paste this into the agent that builds the screen. The docs MCP server returns the same text from get_screen.

Build a trace viewer with Candor UI: TraceViewer draws one run as nested spans on a shared clock.
Pass spans as plain data (id, parent, kind, start, duration, status). Candor does not collect traces.
It opens on the first failure; the span that broke is solid red, the ones that failed because of it are pale red.
A span still running stretches to now and shows no duration.
For multi-agent runs add RunTree beside it, and RunReceipt for cost.
Open a selected span's input and output as Payload blocks; model text in them is text, never markup.
See the agent-trace-viewer pattern and the run-forensics example.

Start from the "Timeline alone" layout: Rows of nested spans as bars on a shared clock, the failing one solid and the ones after it pale.
Candor items: trace-viewer (https://candor.themethodic.com/docs/trace-viewer.md), run-receipt (https://candor.themethodic.com/docs/run-receipt.md).
Install: npx candor-ui add trace-viewer run-receipt
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.