# 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.

- Kind: Component (AI chat)
- Docs: https://ui.minidev.pro/docs/agent-plan
- Source (registry JSON with the full file): https://ui.minidev.pro/r/agent-plan.json
- License: MIT. One file, yours to edit after install.

## 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.

## Installation

### shadcn CLI (copies the source into your project)

```bash
npx shadcn@latest add @minidev/agent-plan
```

Writes `components/ui/agent-plan.tsx` and installs its npm dependencies. Older CLI versions: `npx shadcn@latest add https://ui.minidev.pro/r/agent-plan.json`.

### npm package

```bash
npm i minidev-ui-kit @base-ui/react lucide-react motion
```

Add the tokens to your global stylesheet once:

```css
@import "tailwindcss";
@import "minidev-ui-kit/styles.css";
@source "../node_modules/minidev-ui-kit";
```

Next.js also needs `transpilePackages: ["minidev-ui-kit"]` in next.config.

## Import

After the shadcn install:

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

From the npm package:

```tsx
import { AgentPlan } from "minidev-ui-kit/ui/agent-plan"
```

## Usage

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

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

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `string` | `"Plan"` | no | Header label. |
| `tasks` | `AgentPlanTask[]` | `SAMPLE_TASKS` | no | Tasks in plan order. |
| `defaultOpen` | `boolean` | `true` | no | Whether the task list starts expanded. |
| `onTaskClick` | `(task: AgentPlanTask) => void` | - | no | Makes each task title a button. Fires with the clicked task, e.g. to scroll to its output. |
| `className` | `string` | - | no |  |

## Examples

### Live plan

Drive the statuses from state. Each step moves the highlight to the next row, pops the check and fills the bar.

```tsx
const STEPS = ["Read the export job and its tests", "Stream rows instead of loading them all", "Add a progress event every 1,000 rows", "Run the export test suite"]

function SteppedPlan() {
  const [step, setStep] = React.useState(1)
  const tasks: AgentPlanTask[] = STEPS.map((title, i) => ({
    id: String(i),
    title,
    status: i < step ? "completed" : i === step ? "in_progress" : "pending",
  }))
  return (
    <div className="flex w-full max-w-lg flex-col gap-3">
      <AgentPlan title="Speed up the CSV export" tasks={tasks} />
      <div className="flex gap-2">
        <Button size="sm" variant="outline" disabled={step >= STEPS.length} onClick={() => setStep((s) => s + 1)}>
          Next step
        </Button>
        <Button size="sm" variant="ghost" onClick={() => setStep(1)}>
          Reset
        </Button>
      </div>
    </div>
  )
}
```

### 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.

```tsx
type Todo = { content: string; activeForm: string; status: "pending" | "in_progress" | "completed" }

const todosToTasks = (todos: Todo[]): AgentPlanTask[] =>
  todos.map((t, i) => ({
    id: String(i),
    title: t.status === "in_progress" ? t.activeForm : t.content,
    status: t.status,
  }))

// AI SDK: find the latest call of your todo tool in the message parts
const call = message.parts.findLast((p) => p.type === "tool-todo_write")
<AgentPlan title="Overdue invoices" tasks={todosToTasks(call?.input?.todos ?? [])} />
```

### 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.

```tsx
<AgentPlan
  title="Deploy acme-web to production"
  onTaskClick={(task) => document.getElementById(`step-${task.id}`)?.scrollIntoView()}
  tasks={[
    { id: "build", title: "Build the app", status: "completed", tools: ["run_command"] },
    {
      id: "migrate",
      title: "Run database migrations",
      status: "failed",
      description: "Migration 0042 timed out after 30s",
      subtasks: [
        { id: "m1", title: "0041_add_due_dates", status: "completed" },
        { id: "m2", title: "0042_backfill_totals", status: "failed" },
        { id: "m3", title: "0043_drop_legacy_columns", status: "skipped" },
      ],
      tools: ["run_command", "read_logs"],
    },
    { id: "release", title: "Switch traffic to the new release", status: "pending" },
  ]}
/>
```

## Keyboard interactions

| Key | Action |
| --- | --- |
| `Enter` or `Space` | On the header, collapses or expands the task list. |
| `Enter` or `Space` | 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. |
| `Tab` or `Shift+Tab` | 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 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.

## FAQ

### 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.

## Rules for generating code

- Use semantic tokens only (bg, surface, sunken, border, fg, fg-muted, fg-subtle, ink, accent, success, warning, danger). Never raw hex or palette steps like blue-500.
- Shadows only from the set: shadow-xs, shadow-sm, shadow-raised, shadow-md, shadow-lg, shadow-overlay.
- Numbers use tabular-nums. Dark mode is the `dark` class on <html>; components never branch on theme.

## Dependencies

- npm: `@base-ui/react`, `lucide-react`, `motion`

## Related

- [Agent Trace](https://ui.minidev.pro/docs/agent-trace/md): React timeline of an AI agent run: each tool step shows pending, running, done or error, reports its duration and folds out details. The header sums up the run.
- [Onboarding Checklist](https://ui.minidev.pro/docs/onboarding-checklist/md): A Get started card with a list of setup tasks that toggle between done and pending on click, showing a check box and a strikethrough on completed items.
- [Ai Composer](https://ui.minidev.pro/docs/ai-composer/md): Chat input for AI apps with a multiline textarea, Enter to send, suggestion chips, attach button, model picker and a stop button while a response streams.
- [Artifact Preview](https://ui.minidev.pro/docs/artifact-preview/md): Framed preview for AI generated artifacts such as code, documents or UI, with a title bar, copy button and optional expand action for a full view.
- [Attachment Chip](https://ui.minidev.pro/docs/attachment-chip/md): Compact Tailwind file chip with a paperclip icon, truncated filename and an optional remove button, for attachments in chat composers, emails and forms.
- [Chat Thread](https://ui.minidev.pro/docs/chat-thread/md): Scrolling chat thread for React that renders user, assistant and system messages as bubbles, auto scrolls to the newest one and uses a live log role.

---

All 557 components: https://ui.minidev.pro/llms.txt (full text: https://ui.minidev.pro/llms-full.txt).
