Agent Plan
React AI agent plan and to-do list: pending, in progress, completed, failed and skipped tasks with subtasks, tool chips and a progress bar that fills.
Installation
npx shadcn@latest add @minidev/agent-plan
MiniDev UI is in the shadcn registry directory, so the short form works with no setup. Older CLI versions can use the full URL: npx shadcn@latest add https://ui.minidev.pro/r/agent-plan.json
Usage
import { AgentPlan } from "@/components/ui/agent-plan"
export function Example() {
return (
<AgentPlan />
)
}
API reference
| Prop | Type | Default |
|---|---|---|
| titleHeader label. | string | "Plan" |
| tasksTasks in plan order. | AgentPlanTask[] | SAMPLE_TASKS |
| defaultOpenWhether the task list starts expanded. | boolean | true |
| onTaskClickMakes each task title a button. Fires with the clicked task, e.g. to scroll to its output. | (task: AgentPlanTask) => void | - |
| className | string | - |
When to use
Use it while an agent works through a plan, fed from a todo or plan tool call (Claude Code's TodoWrite, Codex's update_plan, or your own AI SDK tool). Statuses are pending, in_progress, completed, failed and skipped. The active row is highlighted and announced; when the agent moves on, the highlight glides to the next row and the check pops in. For a log of tool calls that already ran use AgentTrace; for a checklist the user ticks use OnboardingChecklist.
Keyboard interactions
| Key | Action |
|---|---|
| EnterorSpace | On the header, collapses or expands the task list. |
| EnterorSpace | On a task with subtasks or tools, shows or hides them. With onTaskClick, the title calls it instead and a separate chevron button toggles the details. |
| TaborShiftTab | Moves between the header and the task buttons. Rows with no details and no onTaskClick are plain text and are skipped. |
Accessibility
- The tasks are an
<ol>labelled withtitle. The running task hasaria-current="step", and each row ends with hidden status text such as ", in progress", because the glyphs arearia-hidden. - A hidden
aria-live="polite"paragraph reads "Working on: " plus the task title when the running task changes, and the title plus "complete" when every counted task is done. - The bar is a
role="progressbar"witharia-valuenowset to completed tasks,aria-valuemaxto tasks that are not skipped, andaria-valuetextsuch as "3 of 5 done". - Under reduced motion the highlight, the check pop and the bar fill change instantly, and the kit stylesheet stops the spinner and the panel height transition.
Frequently asked questions
How do I show a Claude Code or Codex todo list with AgentPlan?
Map each todo to a task. Claude Code's TodoWrite and Codex's update_plan use pending, in_progress and completed, the same strings as status: todos.map((t, i) => ({ id: String(i), title: t.status === "in_progress" ? t.activeForm : t.content, status: t.status })). Codex calls the text step instead of content.
How are tasks counted in the header?
The header shows completed tasks out of the tasks that are not skipped, so a plan with one skipped task still reaches "4 of 4 done" and the bar turns green. A failed task still counts toward the total and turns the bar red.
Why doesn't the check animate when a task completes?
The check pops when a row's status changes while the row stays mounted. Rows are keyed by id, so keep ids stable across updates (the todo's index or your own task id), not a new crypto.randomUUID() on every render. Under reduced motion the change is instant on purpose.
Dependencies
npm
Built from
Examples
Live plan
Drive the statuses from state. Each step moves the highlight to the next row, pops the check and fills the bar.
From a todo tool call
Claude Code's TodoWrite sends pending, in_progress and completed, which map straight onto status. Show activeForm for the running task.
Failure, subtasks and click to jump
A failed task turns the bar red. Subtasks and tools fold out from the chevron; onTaskClick makes each title a button.