Skip to content
WunderUI

Agent Plan

Pro

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

Playground

Ship the Tabs v2 release

2 of 7 done

  1. Read the migration notesDone1m 12s
  2. Audit contrast on the docs siteDone0:48
  3. Sync tokens from FigmaRunning—

    Rewriting the variant map so legacy props keep resolving after the rename.

    Targetpackages/react/tabs.tsxEstimate4 min

  4. Update the token mapQueued—
  5. Run the test suiteQueued—
  6. Publish to npmQueued—
  7. Notify the release channelQueued—

Installation

Agent Plan comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

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

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 for

  • Plan Step for a single step on its own, or your own list of steps
  • Plan Summary for a go or no-go card with the estimate, the tools and the phases
  • Approval Card for a gate that a person has to answer, before or during a run
  • Run Timeline for what a run actually did, with the input and output of each tool call

Live

Follows a run with a progress bar, the count in the header and a Stop button. Stop parks the running step and the same button can read Resume, and a failed step keeps its place with a way forward.

Ship the Tabs v2 release

2 of 7 done

  1. Read the migration notesDone1m 12s
  2. Audit contrast on the docs siteDone0:48
  3. Sync tokens from FigmaRunning—

    Rewriting the variant map so legacy props keep resolving after the rename.

    Targetpackages/react/tabs.tsxEstimate4 min

  4. Update the token mapQueued—
  5. Run the test suiteQueued—
  6. Publish to npmQueued—
  7. Notify the release channelQueued—

Editable

The plan before the run. People reorder with arrow buttons or by dragging, skip and restore steps and add their own, and Start reports only the steps that will run and is disabled when none are left.

Before the run

5 to run · 0 skipped

  1. 1Read the migration notes
  2. 2Audit contrast on the docs site
  3. 3Sync tokens from Figma
  4. 4Run the test suite
  5. 5Publish to npm

Use the arrow buttons to change the order, or drag a row. Skipped steps stay in the plan.

Tree

A plan in phases. A phase is a button that opens and closes its steps and shows how many are done, and it opens by default once one of its steps has started, which you can override.

Ship the Tabs v2 release

2 of 7 done

    1. Read the migration notesDone1m 12s
    2. Audit contrast on the docs siteDone0:48
    1. Sync tokens from FigmaRunning—
    2. Update the token mapQueued—
    3. Run the test suiteQueued—

Pause and resume

onPause adds a Pause button next to Stop. Pass paused and it becomes Resume, and the line under the title says "paused". The callback is the same for both, so toggle your state in it. title is optional when the page already has a heading, and the tree mode can be driven with openIds or expandAll.

Pause

1 of 3 done

  1. Read the token filesDone3.2s
  2. Compare with FigmaRunning—
  3. Open a pull requestQueued—

Keyboard interactions

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.

TaborShiftTab
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.
EnterorSpace
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 and motion

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

The figure shows the live mode. The phase, the edit row, the add form and the Start button belong to the other modes and are listed without a number.

Ship the Tabs v2 release

2 of 7 done

  1. Read the migration notesDone1m 12s
  2. Audit contrast on the docs siteDone0:48
  3. Sync tokens from FigmaRunning—

    Rewriting the variant map so legacy props keep resolving after the rename.

    Targetpackages/react/tabs.tsxEstimate4 min

  4. Update the token mapQueued—
  5. Run the test suiteQueued—
  6. Publish to npmQueued—
  7. Notify the release channelQueued—

  • data-slot="agent-plan"

    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.

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

  • Optional

    Live only. A 120 px bar named Plan progress, as full as the share of steps that are done.

  • Optional

    Live only, and only when a stop handler is passed. A small plain button; its label can change, for example to Resume.

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

  • Optional

    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.

  • Optional

    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.

  • Optional

    Editable only. A field named New step with the placeholder Add a step, and an Add button that adds the step last.

  • Optional

    Editable only, and only when a start handler is passed. A small primary button like Start 4 steps, disabled at zero.

Best practices

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

  • Do

    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.

  • Do

    Pass a stop handler in live mode so a run can always be stopped, and change its label to Resume while it is stopped.

  • Do

    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.

  • Do

    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.

  • Do

    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

    Don't hide a plan the person never approved. A plan that starts itself is a pre-approved plan.

API reference

AgentPlan is a plain component, so the table lists every prop.

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.

PropTypeDefaultDescription
titleReactNode—The heading of the plan. Optional: leave it out when the page already has one; the section is then labelled "Plan".
mode"tree" | "live" | "editable""live" follows a run, lets a person change the plan before it starts, groups the steps into phases.
stepsAgentPlanStep[][]The steps for and . Each is . In only , and a status are used.
groupsAgentPlanGroup[][]The phases for . Each is with as above. overrides the default of opening once a step has started.
subtitleReactNode—Replaces the computed line, such as or . Use it to say that a run is stopped.
onStop() => void—Shows the Stop button in and is called when it is pressed. Pass nothing once the run is over.
stopLabelstring"Stop"The words on the button that shows. Change it to Resume while the run is stopped.
onStart(steps) => void—Shows the Start button in . It receives the steps that will run, as .
onStepsChange(steps) => void—Called in after every move, skip, restore or add, with the whole list as .
hintReactNode"Drag to change the order. Skipped steps stay in the plan."The line under the list in . The default says to drag; write one that names the arrow buttons.
onPause() => void—Shows the Pause button in . Called to pause and to resume, so toggle your state in it.
pausedboolean—Turns the button into Resume and the line under the title into "paused".
pauseLabelstring"Pause"Label of the button while running. Default .
resumeLabelstring"Resume"Label of the button while paused. Default .
openIdsstring[]—Controlled ids of the open phases in . Pair it with .
onOpenIdsChange(ids) => void—Called in with the next list of open phase ids.
expandAllboolean—In , opens () or closes () every phase when the value changes.
classNamestring—Extra classes for the card, for example a width.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("agent-plan")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.