# Agent Plan

The agent's plan as a checklist: follow it live, edit it before the run, or group it into phases.

- Category: AI & Agents
- Page: https://wunderui.com/components/agent-plan
- Tier: Core and Pro

## Install

Agent Plan ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { AgentPlan, AgentPlanDraftStep, AgentPlanGroup, AgentPlanMode, AgentPlanStep } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { AgentPlan } from "@wunderui/react"

export function Plan() {
  return (
    <AgentPlan
      title="Ship the Tabs v2 release"
      steps={[
        { id: "notes", title: "Read the migration notes", status: "done", duration: "1m 12s" },
        { id: "sync", title: "Sync tokens from Figma", status: "running" },
        { id: "npm", title: "Publish to npm", status: "queued" },
      ]}
    />
  )
}
```

Expected result: You should see a card titled Ship the Tabs v2 release with 1 of 3 done, a progress bar a third full and three steps: a green check, a spinner and a grey 3.

## When to use

### Use Agent Plan for

- A plan the agent proposes, that a person can reorder, skip and extend before it runs
- A run followed step by step, with progress and a Stop button
- A long plan in phases that open and close

### Use something else

- [Plan Step](https://wunderui.com/components/plan-step) for a single step on its own, or your own list of steps
- [Plan Summary](https://wunderui.com/components/plan-summary) for a go or no-go card with the estimate, the tools and the phases
- [Approval Card](https://wunderui.com/components/approval-card) for a gate that a person has to answer, before or during a run
- [Run Timeline](https://wunderui.com/components/run-timeline) for what a run actually did, with the input and output of each tool call

## Keyboard

There are no arrow-key shortcuts. Every control is a button or field in the Tab order, and the arrow buttons do everything dragging does.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous control: Stop in live, the phase buttons in tree, and in editable the move and skip buttons of every row, the Add a step field, Add and Start. A disabled button is skipped and the drag grip is not focusable. Focus shows as an indigo border with a 2 px ring. |
| `Enter` or `Space` | Presses the focused button: moves a step up or down, skips or restores it, opens or closes a phase, adds a step, starts or stops the run. |
| `Enter` | In the Add a step field: adds the text as the last step and clears the field. With an empty field it only keeps the focus there. |

## Behavior

What each mode does, what is announced, where focus goes after an edit and what moves.

- **Modes:** Live follows a run, editable is the plan before the run, tree groups steps into phases. Steps feed live and editable, groups feed tree.
- **Name:** The card is a section named by its title. Steps are an ordered list, so a screen reader says how many there are, and each step reads its title and status word.
- **Live region:** Only editable mode announces: after each move, skip, restore or add it says, for example, Sync tokens from Figma moved to position 2 of 5. For live and tree, use your own status line.
- **Focus after an edit:** After a move, focus stays on the same arrow button, or moves to the other arrow at the first or last row. After Skip it lands on the button that runs the step again.
- **Seeding:** In editable mode the steps seed the list, which then belongs to the component and reports every change. Passing the reported steps back changes nothing; a different plan replaces the list.
- **Start:** The Start button reads like Start 4 steps and passes the steps that are not skipped; with every step skipped it is disabled. Skipped steps stay in the list so they can be restored.
- **Drag:** A row can be dragged with a pointer and dropped on another row. It is an extra way to reorder; the arrow buttons do the same from the keyboard.
- **Progress:** In live mode the bar and header count steps that are done. A failed or skipped step is not done, so the bar stops short of full.
- **Phases:** A closed phase is hidden, so its steps are out of the tab order and the accessibility tree. A phase opens by default once any step has started; you can override that.
- **Motion:** The progress fill grows, the running step's icon spins and a phase chevron turns. With reduced motion on, the spinner stands still and the fill jumps to its width; the words keep states readable.

## Anatomy

- `AgentPlan`: A card with a 1 px border, 16 px radius and 16 px padding, named by its title. What it shows depends on the mode: live, editable or tree.
- `Header`: The title in 17 px semibold and a line under it. Live and tree show a count like 2 of 7 done, editable shows 5 to run and 0 skipped, and a subtitle replaces that line.
- `Progress bar`: Live only. A 120 px bar named Plan progress, as full as the share of steps that are done.
- `Stop button`: Live only, and only when a stop handler is passed. A small plain button; its label can change, for example to Resume.
- `Plan step`: Each step is a Plan Step in a list item. The running step shows its detail and the others are compact; numbers continue across phases.
- `Phase`: Tree only. A button with a chevron, the phase title and a count such as 2 of 5, which opens by default once a step in it has started.
- `Edit row`: Editable only. A drag grip, the step number, the title and three buttons (move up, move down, skip); a skipped step shows one button to run it again.
- `Add step form`: Editable only. A field named New step with the placeholder Add a step, and an Add button that adds the step last.
- `Start button`: Editable only, and only when a start handler is passed. A small primary button like Start 4 steps, disabled at zero.

## Best practices

### When to use

- Use it to show what the agent intends to do: live to follow a run, editable to reorder, skip and add steps before it starts, tree for phases. For what a run did, use Run Timeline.

### Do

- Put a gate between the plan and the run. Nothing should start on its own: use a start handler, or pair the plan with an Approval Card, and keep Reject next to Approve.
- Keep the person's edits through the steps-changed handler and run them from the start handler, which receives only the steps that will run.
- Pass a stop handler in live mode so a run can always be stopped, and change its label to Resume while it is stopped.
- Give every step a status, and a start time on the running one. Keep a failed step visible with its reason in the detail and a Retry action.
- Say what changed in a status line next to the plan. Live and tree modes do not announce status changes; only editable mode announces its own edits.
- Write a hint that names the arrow buttons. The default tells people to drag, which a keyboard cannot do.

### Don't

- Don't pass elements as the title in editable mode. The list uses only the id, the title text and a skipped status; a title that is not a string falls back to the id.
- Don't hide a plan the person never approved. A plan that starts itself is a pre-approved plan.

## API reference

### AgentPlan

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the card, for example a width. |
| expandAll | boolean |  | In `tree`, opens (`true`) or closes (`false`) every phase when the value changes. |
| groups | AgentPlanGroup[] | [] | The phases for `tree`. Each is `{ id, title, steps, defaultOpen? }` with `steps` as above. `defaultOpen` overrides the default of opening once a step has started. |
| hint | React.ReactNode | "Drag to change the order. Skipped steps stay in the plan." | The line under the list in `editable`. The default says to drag; write one that names the arrow buttons. |
| mode | "tree" \| "live" \| "editable" | "live" | `live` follows a run, `editable` lets a person change the plan before it starts, `tree` groups the steps into phases. |
| onOpenIdsChange | (ids: string[]) => void |  | Called in `tree` with the next list of open phase ids. |
| onPause | () => void |  | Shows the Pause button in `live`. Called to pause and to resume, so toggle your state in it. |
| onStart | (steps: AgentPlanDraftStep[]) => void |  | Shows the Start button in `editable`. It receives the steps that will run, as `{ id, title, skipped? }`. |
| onStepsChange | (steps: AgentPlanDraftStep[]) => void |  | Called in `editable` after every move, skip, restore or add, with the whole list as `{ id, title, skipped? }`. |
| onStop | () => void |  | Shows the Stop button in `live` and is called when it is pressed. Pass nothing once the run is over. |
| openIds | string[] |  | Controlled ids of the open phases in `tree`. Pair it with `onOpenIdsChange`. |
| paused | boolean |  | Turns the button into Resume and the line under the title into "paused". |
| pauseLabel | string | "Pause" | Label of the button while running. Default `Pause`. |
| resumeLabel | string | "Resume" | Label of the button while paused. Default `Resume`. |
| steps | AgentPlanStep[] | [] | The steps for `live` and `editable`. Each is `{ id, title, status?, detail?, meta?, duration?, since?, action? }`. In `editable` only `id`, `title` and a `skipped` status are used. |
| stopLabel | string | "Stop" | The words on the button that `onStop` shows. Change it to Resume while the run is stopped. |
| subtitle | React.ReactNode |  | Replaces the computed line, such as `2 of 7 done` or `4 to run · 1 skipped`. Use it to say that a run is stopped. |
| title | React.ReactNode |  | The heading of the plan. Optional: leave it out when the page already has one; the section is then labelled "Plan". |

## Examples

### Live: running, stopped, failed, done

### Editable: ready, some skipped, all skipped, one step

### Tree: running, not started, failed

### Pause: one button to hold and resume the run

## In context

### Review: the agent proposes, a person decides

Edit the plan, then press Approve and run or Reject plan. Nothing runs until you approve, and with every step skipped, Approve says so instead of starting an empty run.

### Run: the plan follows the agent

Press Start the run. The running step counts up, Stop parks it and becomes Resume, Retry runs a failed step again, and a status line says what changed so a screen reader hears it.

### Phases: open the one that needs you

A long plan in phases. The finished phase is closed, the failed one is open with its Retry button, and each phase says how many of its steps are done.

## For AI agents

`get_component("agent-plan")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
