Trace

Show the steps in an agent’s turn, with optional status, timing, and expandable output.

  1. You

    Why does pnpm install fail in CI?

  2. Assistant
    1. Thought for 5s

      Compare the manifest and lockfile from the last commit to explain the CI install failure.

    2. Ran pnpm --version
      10.18.0
    3. Ran git diff --stat HEAD~1
      package.json | 2 +-
    4. Failed to run pnpm install --frozen-lockfile
      ERR_PNPM_OUTDATED_LOCKFILE: pnpm-lock.yaml is out of sync with package.json.
    5. Used 2 sources

    The last commit changed a dependency without updating the lockfile. Run pnpm install locally and commit the updated lockfile.

Usage

Use a trace-line on a paragraph for a static step, a link for navigation, or a <summary> for a step with details. Place the title in a span and optional metadata in <small>. Group steps in chronological order with an <ol class="trace">.

<ol class="trace" role="list" aria-label="Build activity">
  <li>
    <details>
      <summary class="trace-line">
        <span>{'Ran node --version'}</span>
        <small>1s</small>
      </summary>
      <div><code>v24.18.0</code></div>
    </details>
  </li>
</ol>

Trace needs only a Basecoat style bundle. Use Message for the reply and Marker for notes between turns. These examples render a transcript directly in HTML. Your application supplies updates if the response streams.

Examples

Trace line

Use plain text for a step with no action or output.

  1. Created branch fix/frozen-lockfile

Status

Describe the state in words. Add color, a spinner, or the shared shimmer utility as a visual cue.

  1. Ran pnpm install

  2. Failed to run pnpm lint

  3. Running pnpm build

  4. Pending: run pnpm test

Description

A short count or duration stays visible beside a long title.

  1. Edited components/settings/notification-preferences-form.tsx+48 −12

  2. Ran pnpm test14s

  3. Searched for useChat8 results

Collapsible

Use a native disclosure to reveal command output. Trace applies Transition Details to its disclosures and rotates the chevron as each step opens.

  1. Ran node --version
    v24.18.0

Open state

Add open to expand a step initially. Application code can read or set the native details.open property and listen for toggle.

  1. Ran node --version
    v24.18.0
  2. Ran pnpm --version
    10.18.0

Dialog

Open a Dialog when the details need more room.

Searched the web for cache keys

Three results were used in the response.

  1. Caching build outputs
  2. Image optimization reference
  3. Deploy hooks and cache keys

Sheet

Use the Sheet setup to open the file list alongside the conversation.

Explored 4 files

Files read while preparing the response.

  1. package.json

  2. pnpm-lock.yaml

  3. pnpm-workspace.yaml

  4. README.md

Group

  1. Searched for minimumReleaseAge

  2. Read pnpm-workspace.yaml

  3. Ran pnpm install

Sources

Keep source links individually focusable inside the disclosure.

Chain of thought

Nest related steps under a short activity summary.

  1. Looking into the slow deploy
    1. Searched for the checkout build log

      Found logs for the last twelve builds.

    2. Read the last twelve deploys

    3. Searching for the cache key

      Reading the restore step in the build log.

Commit

Expand a commit to see its changed files and line counts.

  1. Committed a1b2c3: Fix the login redirect
    1. src/routes/login.ts+1 −1
      - return redirect(”/”)
      + return redirect(next)
    2. tests/login.ts+8

Whole turn

Keep successful and failed steps together under the turn summary.

  1. Worked for 2m 4s, 1 command failed
    1. Thought12s

      Check the installed package managers before starting the build.

    2. Ran 2 commands, 1 failed
      1. Ran node --version
        v24.18.0
      2. Failed to run pnpm --version
        pnpm: command not found
    3. Read apps/v4/lib/docs.ts

Reasoning

Render a short progress summary above the reply.

  1. You

    Why is the checkout deploy so slow?

  2. Assistant
    1. Thought

      Compared the cache restore and install timings in recent builds.

    The dependency cache is missing on each build. Check which files contribute to the cache key.

Tool

A finished tool call can expose its output. A denied tool call is a text row.

  1. You

    Which package managers are installed?

  2. Assistant
    1. Ran node --version
      v24.18.0
    2. Ran npm --version
      11.6.2
    3. Denied corepack enable

    Node and npm are installed. Corepack was not enabled.