Skip to content

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.

src/registry/ui/agent-plan.tsx/r/agent-plan.json

Installation

bash
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

tsx
import { AgentPlan } from "@/components/ui/agent-plan"

export function Example() {
  return (
    <AgentPlan />
  )
}

API reference

AgentPlan props
PropTypeDefault
titleHeader label.string"Plan"
tasksTasks in plan order.AgentPlanTask[]SAMPLE_TASKS
defaultOpenWhether the task list starts expanded.booleantrue
onTaskClickMakes each task title a button. Fires with the clicked task, e.g. to scroll to its output.(task: AgentPlanTask) => void-
classNamestring-

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

Keyboard interactions
KeyAction
EnterorSpaceOn the header, collapses or expands the task list.
EnterorSpaceOn 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.
TaborShiftTabMoves 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 with title. The running task has aria-current="step", and each row ends with hidden status text such as ", in progress", because the glyphs are aria-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" with aria-valuenow set to completed tasks, aria-valuemax to tasks that are not skipped, and aria-valuetext such 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

@base-ui/reactlucide-reactmotion

Built from

No other MiniDev files

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.

All AI chat UI components for React