Run trace

A React component in Beamline's AI & agents category.

One agent run as a waterfall: every step (model calls, tools, retrieval, checks, sub-agents) nested under the step that started it, each a bar on a shared time axis, with retries as separate attempts on the same bar, tokens and cost per step and for the run; while it runs the bars grow live, and choosing a step shows its timing, attempts, input and output beside the trace.

Use it for

Debugging or reviewing an agent run: what ran, in what order, what waited on what, what failed and was retried, and what it cost.
An observability page for model and tool calls (spans from your tracing).

Not for

A single tool call in a conversation (tool-call).
The agent's thinking in words (reasoning).
Background jobs a person follows (task-rows).
The designed workflow before it runs (flowchart).

Anatomy

header: the run's status (a glyph and a word), total time, how many steps and how many failed, tokens in and out, cost
axis: time marks across the lane (0, 2 s, 4 s…), a line at now while running
row: indent and a chevron for steps with children, the kind's glyph (model, tool, retrieval, check, agent, wait), the name and the model; the bar on the lane from start to end in the kind's colour; failed attempts before it as hatched segments with a gap; the duration at the end
selected step: the row ringed and a detail panel (beside the trace when wide, under it when narrow): name, kind, start and duration, attempts with their errors, tokens and cost, input and output
running step: the bar's open end grows with time and carries a soft edge; the duration counts

Variants

density: compact, default

States

running (live)
succeeded
failed (the failing step and its parents are marked)
retried
cancelled
collapsed
selected
empty (no steps yet)

Keyboard

The trace is a tree grid with one tab stop: ↑/↓ move between visible steps, → opens a step or goes to its first child, ← closes it or goes to its parent
Home/End go to the first and last step; Enter or Space shows the step's detail
Escape clears the selection

Motion

New steps grow into the list and the rows below slide down (useFlip). While the run is live the open bars grow on a clock that runs only while something is running and the trace is on screen, then stops. Opening and closing a step folds its children. The detail cross-fades to the chosen step. Reduced motion: bars jump to their length each tick of the clock; nothing slides.

Props

Prop	Type	Default	Description
`spans` (required)	`TraceSpan[]`	—
`now`	`number`	—	ms since the run started, for live bars; omit to let the trace keep its own clock while a span is running.
`title`	`ReactNode`	—	The run's name (the request it answered).
`selected / defaultSelected / onSelectedChange`	`string \| null`	—
`expanded / defaultExpanded / onExpandedChange`	`string[]`	—	Open steps. Default: every step.
`density`	`"compact" \| "default"`	—
`currency`	`string`	—	Cost symbol. Default "$".
`className / classNames / style / ref`	`root`	—

Built from

spinner

Dependencies

lucide-react

Import

import { RunTrace } from "@/components/run-trace/run-trace";

Get it

Run trace is part of Beamline: 200+ components and 50+ complete screens for React that your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 launch price, one payment, no subscription, lifetime updates, one licence for your whole team. Get Beamline · Connect your agent