# Agent Todos

> The plan an agent keeps while it works, one line per step. Handles steps in progress, failed steps and plan changes mid-run.

Canonical: https://hextaui.com/blocks/agent-todos
Last updated: 2026-10-29

## Overview

Coding agents like Claude Code, Codex and Gemini CLI keep a written plan while they work, through tools such as TodoWrite, update_plan and write_todos. Agent Todos turns that plan into one line per step, with the step in progress spelled out (“Running the tests”) and how long each one took.

Every step moves from backlog to to do, in progress, and then done, failed or cancelled. When the agent rewrites its plan, new steps highlight, removed ones collapse out and a short note says what changed. A failed step keeps its reason in view, and long runs of finished steps fold away so the current work stays on screen.

AgentTodosStatus puts the current step and a count in one line above the composer, and AgentTodosReview lets people edit, reorder, add and remove steps before anything runs, then start with ⌘↵. Adapters read each agent’s tool format, including input that is still streaming, and Tool Calls can show the work inside any step.

## Installation

### Step 1: Get HextaUI Pro

One payment unlocks every block, including future ones. [See pricing](https://hextaui.com/pricing).

### Step 2: Add the Pro registry to components.json

```json title="components.json"
{
  "registries": {
    "@hextaui-pro": {
      "url": "https://hextaui.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${HEXTAUI_PRO_TOKEN}"
      }
    }
  }
}
```

### Step 3: Add your token

Create a token on your [account page](https://hextaui.com/account) and put it in `.env.local` as `HEXTAUI_PRO_TOKEN`.

### Step 4: Add the block

```bash
npx shadcn@latest add @hextaui-pro/agent-todos
```

## Usage

### With the AI SDK

getTodosFromParts reads the latest TodoWrite, update_plan or write_todos call in a message, even while its input is still streaming. Show the list in the message and the status pill above the composer.

```tsx
"use client"

import { useChat } from "@ai-sdk/react"

import { AgentTodos, AgentTodosStatus } from "@/components/blocks/agent-todos/agent-todos"
import { getTodosFromParts } from "@/components/blocks/agent-todos/todos"

export function Chat() {
  const { messages, status } = useChat()
  const busy = status === "submitted" || status === "streaming"
  const last = messages.at(-1)
  const current = last?.role === "assistant" ? getTodosFromParts(last.parts) : null

  return (
    <div className="flex flex-col gap-4">
      {messages.map((message) => {
        const plan = message.role === "assistant" ? getTodosFromParts(message.parts) : null
        return plan ? (
          <AgentTodos
            key={message.id}
            todos={plan.todos}
            explanation={plan.explanation}
            running={busy && message.id === last?.id}
          />
        ) : null
      })}
      {current ? <AgentTodosStatus todos={current.todos} running={busy} /> : null}
    </div>
  )
}
```

### Review before running

Let people edit, reorder, add and remove steps before the agent starts. Run plan or ⌘↵ hands back the cleaned-up list.

```tsx
"use client"

import * as React from "react"

import { AgentTodosReview } from "@/components/blocks/agent-todos/todo-review"
import type { Todo } from "@/components/blocks/agent-todos/todos"

export function PlanApproval({
  proposed,
  onRun,
}: {
  proposed: Todo[]
  onRun: (plan: Todo[]) => void
}) {
  const [draft, setDraft] = React.useState(proposed)

  return <AgentTodosReview todos={draft} onChange={setDraft} onApprove={onRun} />
}
```

### With incremental task tools

For tools that create and update one task at a time, like Claude Code’s TaskCreate and TaskUpdate, fold each call into the list with applyTaskEvent.

```tsx
"use client"

import * as React from "react"

import { AgentTodos } from "@/components/blocks/agent-todos/agent-todos"
import { applyTaskEvent, type TaskEvent, type Todo } from "@/components/blocks/agent-todos/todos"

export function useTaskList() {
  const [todos, setTodos] = React.useState<Todo[]>([])
  const apply = React.useCallback(
    (event: TaskEvent) => setTodos((current) => applyTaskEvent(current, event)),
    []
  )
  return { todos, apply }
}

export function Tasks({ todos, running }: { todos: Todo[]; running: boolean }) {
  return <AgentTodos todos={todos} running={running} />
}
```

## Anatomy

The parts you compose, from the outside in.

| Part | Description |
| --- | --- |
| `AgentTodos` | The full list with its header, progress bar, explanation and plan-change note. |
| `AgentTodosStatus` | A one-line pill with the current step, opening the list in a popover. |
| `AgentTodosReview` | The editable plan shown before the agent starts. |
| `TodoMark` | The status mark on its own, for custom layouts. |
| `getTodosFromParts, fromTodoWrite, fromUpdatePlan, fromWriteTodos, applyTaskEvent` | Adapters from each agent’s tool format to Todo items. |

## API reference

### AgentTodos

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `todos` | `Todo[]` | – | Steps in order. |
| `explanation` | `string` | – | Why the plan looks the way it does, shown under the progress bar. Codex sends this with update_plan. |
| `running` | `boolean` | – | Whether the agent is working. Defaults to true while any step is in progress. |
| `title` | `string` | `"Tasks"` | Header label and region name. |
| `collapsible` | `boolean` | `true` | Let the header fold the list away. |
| `defaultOpen` | `boolean` | `true` | Start open. |
| `foldAfter` | `number` | `6` | Fold the finished steps at the top once the list is longer than this. |

### Todo

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | – | Stable id. Plan changes are detected by id. |
| `content` | `string` | – | What to do, in the imperative: “Run the tests”. |
| `activeForm` | `string` | – | What it’s doing, shown while in progress: “Running the tests”. |
| `status` | `"backlog" \| "pending" \| "in_progress" \| "completed" \| "failed" \| "cancelled"` | – | The stage. pending reads as To do. |
| `error` | `string` | – | Shown under a failed step. |
| `duration` | `number` | – | Stored seconds, for history. |
| `details` | `ReactNode` | – | Opens under the step, usually Tool Calls. |

### AgentTodosStatus

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `todos` | `Todo[]` | – | The same list. Renders nothing when empty. |
| `running` | `boolean` | – | Animates the mark and shimmer while true. |
| `explanation` | `string` | – | Passed to the list in the popover. |

### AgentTodosReview

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `todos` | `Todo[]` | – | The proposed plan. |
| `onChange` | `(todos: Todo[]) => void` | – | Called on every edit. |
| `onApprove` | `(todos: Todo[]) => void` | – | Called from Run plan or ⌘↵, with empty steps removed and text trimmed. |
| `onCancel` | `() => void` | – | Shows Cancel and handles Escape. |
| `title` | `string` | `"Review the plan"` | Heading. |
| `approveLabel` | `string` | `"Run plan"` | Button label. |

### getTodosFromParts(parts)

Returns { todos, explanation? } from the newest TodoWrite, update_plan or write_todos call in an AI SDK message, or null.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `parts` | `UIMessage["parts"]` | – | Works on static and dynamic tool parts, including input that is still streaming. |

### applyTaskEvent(todos, event)

Folds one TaskCreate or TaskUpdate call into the list. A status of deleted removes the task.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `event` | `{ type: "create", id, subject, activeForm? } \| { type: "update", id, status?, subject?, activeForm? }` | – | The call, normalised. |

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` | Opens or folds the list from its header, or a step’s details. |
| `⌘` `↵` | Runs the plan while it’s being reviewed, unless you’re typing in another field. |
| `Enter` | In review, adds a step below the current one. |
| `⌫` | In review, removes an empty step and moves to the one above. |
| `⌥` `↑` | In review, moves the step up. ⌥↓ moves it down. |
| `↑` `↓` | In review, moves between steps. |
| `Esc` | Cancels the review when onCancel is set. |

## Accessibility

- The list is a labelled region with an ordered list, and each step’s name includes its stage, such as “Running the tests, In progress”.
- A hidden progressbar reports how many steps are done.
- Starting, finishing and failing a step are announced through a polite live region, along with plan changes. Timer ticks are not announced.
- The status pill’s label reads the current step and the count, and it opens the list in a focus-managed popover.
- Review fields are labelled by step number, moves are announced (“Moved to step 2 of 5”), and Enter waits while an input method is composing.
- With reduced motion, the in-progress ring stops spinning, checks appear without drawing, and steps slide into place instantly.

## Built with

The free HextaUI components Agent Todos is made from. Each one installs on its own.

- [Button](https://hextaui.com/docs/button) - Buttons in every variant and size, with a built-in loading, success and error flow that skips the spinner for fast requests.
- [Collapsible](https://hextaui.com/docs/collapsible) - A panel that shows and hides with height motion you can reverse mid-way, without jumping the layout.
- [Kbd](https://hextaui.com/docs/kbd) - Key caps for shortcuts that show the right symbols on every platform, read them out properly and press down with the real keys.
- [Popover](https://hextaui.com/docs/popover) - A floating panel anchored to a trigger that resizes smoothly with its content and follows the trigger’s direction.
- [Tooltip](https://hextaui.com/docs/tooltip) - A short hint on hover or keyboard focus that opens after a brief rest, switches instantly between neighbours and shows shortcuts.

## Code

5 files, added to components/blocks/agent-todos.
