affectUI › Components › Agents

Agent Checkpoints

An agent's run as a line of checkpoints, like git for agents – rewind to any of them and a new attempt branches out of it, while the one it left fades back but stays.

Part of affectUI Pro. Install: npx shadcn@latest add https://www.affectui.com/r/agent-checkpoints.json · Import from @/components/ui/agent-checkpoints

When to use

Long agent runs where a wrong turn shouldn't cost the whole run – rewind to the last good checkpoint and let it try again
Showing that nothing is lost: an attempt you rewound from stays visible, faded, and you can go back to it
Coding agents, research agents, anything that saves its state step by step

When not to use

Steps of a plan that haven't happened yet – use Agent Plan
How long each step took against its plan – use Plan vs Actual
Several agents at once – use Agent Fleet

Usage

import { AgentCheckpoints, type Checkpoint } from "@/components/ui/agent-checkpoints";

const checkpoints: Checkpoint[] = [
  { id: "c1", title: "Read the brief", at: 9_000 },
  { id: "c2", parent: "c1", title: "Built the pricing table", files: 3, at: 64_000 },
  { id: "c3", parent: "c2", title: "Tests failing – 4 of 12", status: "failed", at: 131_000 },
  // A second checkpoint after c2 starts a new attempt
  { id: "c4", parent: "c2", title: "Switched to Stripe Elements", status: "running", at: 169_000 },
];

export function Run() {
  return <AgentCheckpoints checkpoints={checkpoints} head="c4" onRewind={(c) => agent.restoreFrom(c.id)} />;
}

Props

Name	Type	Default	Description
`checkpoints`	`Checkpoint[]`		{ id, title, icon?, parent?, status?, at?, files?, cost? } in the order they were taken – pass them again whenever one is added or changes; icon is a small mark before the title, e.g. the logo of the tool it worked with
`parent`	`string`		Per checkpoint, the one it follows – a checkpoint whose parent already has a later one starts a new attempt on its own lane
`status`	`"running" \| "done" \| "failed" \| "stopped"`	`"done"`	Per checkpoint – running shimmers, failed gets a badge, stopped means you rewound away while the agent worked toward it
`head`	`string`	`the last checkpoint`	Id of the checkpoint the agent stands on – the way to it is blue, everything off it fades back
`onRewind`	`(checkpoint: Checkpoint) => void`		Rewind was pressed – add a new checkpoint with this one as its parent, and move head to it
`task`	`string`		What the run is for, next to the title
`formatTime`	`(ms: number) => string`	`0:42 / 1:05`	Formats at
`formatCost`	`(amount: number) => string`	`dollars, e.g. "$0.42"`	Formats the total in the bar on top
`title`	`string`	`"Checkpoints"`	Heading of the bar
`className`	`string`		Extra class on the root

Keyboard

↑ / ↓: Moves between the checkpoints
Home / End: Jumps to the first or the last checkpoint
Enter / Space: Rewinds to the focused checkpoint

Accessibility

The checkpoints are an ordered list with one tab stop; the arrow keys move between them
Every row says its title, its attempt, its status and whether it's current or left behind; the current one has aria-current="step"
The Rewind button is a pointer shortcut – from the keyboard, Enter on the row does the same
The count in the bar on top is announced politely when it changes
Status is never color alone: failed has a badge, stopped says so, the current checkpoint is announced

Responsive

Every row has a fixed height, so nothing jumps when a checkpoint finishes or fails – Rewind takes the place of files and time
Past fourteen checkpoints the list scrolls inside the card and keeps the current one in view
Narrow, the task and the file counts give way first
Dark mode built in: switches when an ancestor (usually <html>) has the class dark or data-theme="dark"

Requirements

React 19

Agent Plan – An agent's step-by-step plan to review before it runs – rename, drag to reorder, remove or add steps, then watch each one run with live timers and retry from a failed step
Plan vs Actual – An agent's plan against what really happens – every step's bar grows over its dashed planned ghost, overruns turn amber, the steps after it slide right, and the expected finish moves away from the planned one
Agent Tree – Who started whom – an orchestrator and its sub-agents as a live tree, with status, cost and time on every card, costs rolling up each branch, and branches that fold to one line
Agent Ledger – Everything an agent changed in your systems, each change with an undo – before and after per row, and pointing at Undo shows what builds on it: what would be undone too, and what can't be taken back