Run Timeline
SaveA run's state in an Agent State pill, a progress hairline, and its steps in order on a rail, with start times, durations, and errors.
- Category
- Agent
- Version
- 0.3.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Update the rate-limit docs
1 of 3 steps done
search_docs, Done
Found 3 pages
· 800 msedit_files, Running
Update the limits table
open_pull_request, Queued
Installation
npx @shakenui/cli add run-timelineReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add run-timeline --dry-runUsage
import { RunTimeline } from "@/components/shaken/agent/run-timeline";
export default function RunTimelineExample() {
return (
<RunTimeline
className="w-full max-w-md"
run={{
title: "Update the rate-limit docs",
status: "running",
steps: [
{ id: "1", name: "search_docs", kind: "tool", status: "succeeded", summary: "Found 3 pages", startedAt: "2026-11-14T10:00:00.600Z", finishedAt: "2026-11-14T10:00:01.400Z" },
{ id: "2", name: "edit_files", kind: "tool", status: "running", summary: "Update the limits table", startedAt: "2026-11-14T10:00:01.600Z" },
{ id: "3", name: "open_pull_request", kind: "tool", status: "queued" },
],
}}
/>
);
}States
Every state, rendered from local fixture data.
Research run
No steps yet
Steps appear here as the agent works.
Research run
1 of 3 steps done
search_docs, Done
Found 3 pages
· 800 msfetch_page, Running
Read /docs/api/rate-limits
open_pull_request, Queued
Research run
2 of 3 steps done
search_docs, Done
Found 3 pages
· 800 msfetch_page, Done
Read /docs/api/rate-limits
· 1.3 sopen_pull_request, Queued
Research run
3 of 3 steps done · 3.4 s
search_docs, Done
Found 3 pages
· 800 msfetch_page, Done
Read /docs/api/rate-limits
· 1.3 sopen_pull_request, Done
Research run
1 of 3 steps done · 2.3 s
fetch_page failed: 504 Gateway Timeout.
search_docs, Done
Found 3 pages
· 800 msfetch_page, Failed
504 Gateway Timeout
· 1.3 sopen_pull_request, Skipped
Research run
2 of 3 steps done · 2.5 s
search_docs, Done
Found 3 pages
· 800 msfetch_page, Done
Read /docs/api/rate-limits
· 1.3 sopen_pull_request, Skipped
API
| Prop | Type | Default | Description |
|---|---|---|---|
| run | Pick<AgentRun, "title" | "status" | "steps" | "error" | "createdAt" | "finishedAt"> | — | The run to show. Times are shown in UTC so server and client render the same text. |
| activity | "thinking" | "searching" | "working" | "planning" | "listening" | "shaping" | "working" | Which Agent State mark animates in the header while the run is running. |
Accessibility
- The run status pill is a live region whose text is exactly the status (Running, Needs approval, Succeeded, Failed, Cancelled), so changes are announced.
- Each step includes its status as screen-reader text and as a visible label; the progress line and glyphs are decorative.
- Failures are shown as text, not only red.
- With reduced motion the running marks hold a still frame and status changes are instant.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/agent/run-timeline.tsxrun-timeline- Also installs agent-run@0.1.2registry dependency
- Also installs step-list@0.3.0registry dependency
- Also installs agent-state@0.1.0registry dependency
- npm packages: noneReact and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/run-timeline/0.3.0.json.
agent/run-timeline.tsxShowHide
import type { ComponentProps } from "react";
import type { AgentRun, RunStatus } from "./agent-run";
import { type AgentActivity, type AgentPhase, AgentState } from "./agent-state";
import { StepList } from "./step-list";
const runStatus: Record<RunStatus, { label: string; phase: AgentPhase }> = {
queued: { label: "Queued", phase: "idle" },
running: { label: "Running", phase: "active" },
"waiting-for-approval": { label: "Needs approval", phase: "waiting" },
succeeded: { label: "Succeeded", phase: "done" },
failed: { label: "Failed", phase: "failed" },
cancelled: { label: "Cancelled", phase: "cancelled" },
};
const ease = "ease-[cubic-bezier(0.23,1,0.32,1)]";
export interface RunTimelineProps extends Omit<ComponentProps<"section">, "children"> {
run: Pick<AgentRun, "title" | "status" | "steps" | "error" | "createdAt" | "finishedAt">;
/** Which Agent State mark animates while the run is running. Defaults to working. */
activity?: AgentActivity;
}
/**
* The run's state and its steps in order on a hairline rail, with start times and durations.
* The divider under the header doubles as a progress line.
*/
export function RunTimeline({ run, activity = "working", className, ...props }: RunTimelineProps) {
const meta = runStatus[run.status];
const done = run.steps.filter((step) => step.status === "succeeded").length;
const settled = run.steps.filter((step) => step.status !== "queued" && step.status !== "running").length;
const progress = run.status === "succeeded" ? 1 : run.steps.length ? settled / run.steps.length : 0;
const total = run.createdAt && run.finishedAt ? formatDuration(run.createdAt, run.finishedAt) : "";
return (
<section
aria-label={`${run.title} timeline`}
data-status={run.status}
className={[
"rounded-xl border bg-white text-zinc-950 shadow-[0_1px_2px_rgb(0_0_0/0.04)] transition-[border-color] duration-200 motion-reduce:transition-none",
"dark:bg-black dark:text-white dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.06)]",
run.status === "failed" ? "border-red-500/35" : "border-zinc-950/10 dark:border-white/10",
className,
]
.filter(Boolean)
.join(" ")}
{...props}
>
<header className="flex items-start justify-between gap-3 px-4 pt-3.5 pb-3">
<div className="min-w-0">
<h3 className="truncate text-sm leading-6 font-semibold">{run.title}</h3>
<p className="text-xs text-zinc-500 tabular-nums">
{run.steps.length ? `${done} of ${run.steps.length} steps done` : "No steps yet"}
{total ? ` · ${total}` : ""}
</p>
</div>
{/* A live region whose text is exactly the status label; the mark is decorative. */}
<AgentState status size="sm" activity={activity} phase={meta.phase} label={meta.label} className="mt-0.5" />
</header>
{/* The divider is the progress line: it fills as steps settle. */}
<div aria-hidden="true" className="relative h-px overflow-hidden bg-zinc-950/[0.07] dark:bg-white/[0.08]">
<span
className={[
"absolute inset-0 origin-left transition-[scale,background-color] duration-500 motion-reduce:transition-none",
ease,
run.status === "failed" ? "bg-red-500/70" : run.status === "waiting-for-approval" ? "bg-amber-500/70" : "bg-zinc-950/40 dark:bg-white/50",
].join(" ")}
style={{ scale: `${progress} 1` }}
/>
</div>
{run.status === "failed" && run.error ? (
<p className="mx-4 mt-4 rounded-lg border border-red-500/35 bg-red-500/[0.08] px-3 py-2 text-sm text-red-700 dark:text-red-300">{run.error}</p>
) : null}
<div className="px-4 py-4">
{run.steps.length ? (
<StepList
steps={run.steps.map((step) => ({
id: step.id,
status: step.status,
label: step.kind === "tool" ? <span className="font-mono text-[13px]">{step.name}</span> : step.name,
detail: step.status === "failed" && step.error ? step.error : step.summary,
meta: step.startedAt ? (
<>
<time dateTime={step.startedAt}>{formatTime(step.startedAt)}</time>
{step.finishedAt ? ` · ${formatDuration(step.startedAt, step.finishedAt)}` : ""}
</>
) : undefined,
}))}
/>
) : (
<p className="text-sm text-zinc-500">Steps appear here as the agent works.</p>
)}
</div>
</section>
);
}
function formatTime(iso: string): string {
const date = new Date(iso);
return Number.isNaN(date.getTime()) ? "" : date.toISOString().slice(11, 19);
}
function formatDuration(start: string, end: string): string {
const ms = new Date(end).getTime() - new Date(start).getTime();
if (!Number.isFinite(ms) || ms < 0) return "";
return ms < 1000 ? `${ms} ms` : `${(ms / 1000).toFixed(1)} s`;
}