Skip to content

Trace

The steps an agent takes, as lines that can expand to show their detail.

Searched for minimumReleaseAge3 resultsRead pnpm-workspace.yamlEdited pnpm-workspace.yaml+2 −1
Running: Running pnpm build

Installation

  1. Add the registryOnce per project
  2. Add trace

Usage

A line is text, not a control. To make a line expandable, put it in a TraceCollapsibleTrigger, which turns it into a button and adds a caret. To make a line open a page, a Dialog or a Sheet, put it in a link or in that component's trigger instead.

TraceTitle stays on one line and truncates. TraceDescription doesn't truncate, so keep it short, such as a duration or a count.

Composition

Examples

States

status sets the state of the work: pending before it starts, running while it happens, and error when it failed. running adds a shimmer to the title. Leave status out once the work is done. The color and motion aren't announced, so say the state in the title too, as in "Running pnpm test" or "Failed to run pnpm typecheck". The shimmer stops when reduced motion is preferred.

Ran pnpm lintFailed: Failed to run pnpm typecheckRunning: Running pnpm testPending: Deploy a preview

Reasoning

Show a model's reasoning as a line that expands to show its thoughts. While the reasoning streams, title the line "Thinking" and give it the running status. Once it's done, say how long it took.

The person wants to know why the build is slow. The log shows the type check takes 41 of the 58 seconds, so that's the place to start. Skipping the library check would hide errors in our own declaration files, so caching the build info with incremental is the safer fix.

To open the line while the thoughts stream and close it when they finish, control open. Once someone opens or closes it themselves, keep their choice. Until the first thoughts arrive, show the line on its own, since there's nothing to expand.

Sources

The sources a reply read can go under a single line that expands to show a link for each one. Render each source's line as a link with render, and give it a focus ring, since a plain line has none.

To cite a source within the reply itself, use a Citation.

Nested

Put a Trace in TraceCollapsibleContent to group steps under one line, such as a subagent's steps. The nested content is indented to align with the title above it.

Searched for createInvoiceRead src/billing/invoices.tsRead src/billing/plans.ts

Props

Base UI's styling (opens in a new tab) and composition (opens in a new tab) guides say more about className, style and render.

Trace

TraceLine

TraceIcon

TraceTitle

TraceDescription

TraceCollapsible

TraceCollapsibleTrigger

TraceCollapsibleContent