Without the chart

useAgentTelemetry runs the chart's event handling and anomaly detection without a canvas. Use it for your own UI, or with four small components built on it.

'use client';
import {
  AgentRoster,
  AgentStatusBadge,
  AgentTimeline,
  AnomalyBanner,
  useAgentTelemetry,
  type AgentSource,
} from '@dan-build/agentstat';

// `source` is the stream your agents push into, or connectSse('/api/agents').
export default function AgentPanel({ source }: { source: AgentSource }) {
  const agents = useAgentTelemetry(source);

  const first = agents[0];

  return (
    <>
      <AnomalyBanner agents={agents} />
      <AgentRoster agents={agents} />
      {first && <AgentStatusBadge agent={first} />}
      {first && <AgentTimeline agent={first} />}
    </>
  );
}

Pass the same stream your agents push into (see Event streams); a chart can share it. An app that renders only the chart doesn't ship these components.

useAgentTelemetry

useAgentTelemetry(source: AgentSource | undefined, options?: TelemetryOptions): AgentTelemetry[]

It updates every half second and returns one entry per agent:

Field	Meaning
`id`, `name`	The agent.
`status`	Its current status.
`statusMs`	How long it has had that status.
`tool`	The innermost open tool call (`''` if unnamed), or `null`.
`tokensRate`, `totalTokens`	Current rate and tokens counted so far.
`ttftMs`	Time to first token, or `null`.
`health`	0–100, or `null` before the first health tick.
`anomalies`	Anomalies active now.
`history`	Status history within `historySeconds`, oldest first: `{ status, fromMs, toMs }`, in ms ago (`toMs` 0 = now).

Options:

Option	Default	Meaning
`agents`	—	Agents known up front, like the chart's `agents` prop. The source adds more.
`anomalyDetection`	`true`	Detect stalls, spikes and thrash. Note: on by default here, off on the chart.
`anomalyConfig`	—	Overrides, as on the chart.
`historySeconds`	`300`	Status history kept for `history`.
`onAnomaly`, `onAnomalyEnd`, `onHealthChange`	—	Same as the chart's callbacks.

The components

Component	Shows
`AgentStatusBadge`	One agent's status in words and an icon, with the open tool and time in status: "Waiting · bash · 12s".
`AnomalyBanner`	Active anomalies, one line each. Screen readers hear each once, when it starts, escalates or ends.
`AgentRoster`	A table of every agent: status, rate, tokens, health. `caption` sets its accessible name (default "Agents").
`AgentTimeline`	One agent's status over the last `windowSeconds` (default 300) as a bar, a segment per status. Statuses differ by pattern as well as color and are listed for screen readers.

All four take theme ('light' | 'dark' | 'system', default 'system'), className and style. They use the chart's colors and show status in words and icons, not color alone.

shadcn/ui

The same four components are available as shadcn/ui source — Tailwind, shadcn's Badge, Alert and Table, and lucide icons — to copy into your app and restyle:

npx shadcn@latest add https://raw.githubusercontent.com/dan-build/agentstat/main/public/r/agent-roster.json
# also: agent-status-badge, anomaly-banner, agent-timeline

To add them by name, register the namespace in components.json:

{
  "registries": {
    "@agentstat": "https://raw.githubusercontent.com/dan-build/agentstat/main/public/r/{name}.json"
  }
}

npx shadcn@latest add @agentstat/agent-roster

They take the agents from useAgentTelemetry and keep its behavior through two exports of the library: useAnomalyAnnouncer (announce each anomaly once) and timelineBars (the timeline's layout).