Agent todo list

Show caller-owned task progress beside an AI draft or transcript.

Preview

Gather changes — complete
Draft summary — in progress
Review next steps — not started

Design guidance

Use AgentTodoList when an assistant or transcript needs to show a plan whose status comes from the caller. The summary is one keyboard-accessible disclosure. It reports complete tasks out of the total; rows are ordered and do not invite edits. Keep the containing Composer surface with Composer, and use AgentTodoList for the task layout inside it.

Installation

Install

npx shadcn@latest add https://ghost-ui.com/r/todo-list.json

Basic usage

12345import { AgentTodoList, type TodoItem } from "@/components/ui/agent-todo-list";

const tasks: TodoItem[] = [{ id: "gather", label: "Gather changes", status: "complete" }, { id: "draft", label: "Draft summary", status: "active" }, { id: "review", label: "Review next steps", status: "pending" }];

<AgentTodoList title="Weekly update" items={tasks} />

Structures

The title and derived completion count form the disclosure summary. The ordered task rows appear in its panel. Status belongs to each caller-provided item; the component does not run tasks or change their status.

Examples

Thumbnail

A compact snapshot of the same weekly-update plan.

Attached to a Composer

The plan sits with the draft it describes.

Gather changes — complete
Draft summary — in progress
Review next steps — not started

Transcript plan

Use the same list in a transcript without a Composer surface.

Gather changes — complete
Draft summary — in progress
Review next steps — not started

Not started

All tasks are pending and the summary starts collapsed.

In progress

A completed task, active task, and pending task share the same ordered list.

Complete

The caller reports every task complete; the derived count reflects it.

Expanded in progress

Set defaultOpen when the initial list should be visible.

Gather changes — complete
Draft summary — in progress
Review next steps — not started

Long task label

Task copy wraps while each status indicator stays in the same narrow lane.

Compare the rollout notes with the customer feedback and flag any change that needs an owner before the weekly update is shared — in progress

Caller-owned status update

The caller changes item data after its own action. TodoList reflects the new data and does not own that transition.

Gather changes — complete
Draft summary — in progress
Review next steps — not started

Failed task

Failed tasks keep their reason and do not contribute to completion.

Gather changes — complete
Draft summary — failedStaging notes are unavailable. The gathered changes remain in the plan.
Review next steps — not started

Cancelled task

Stopped work remains distinct from completed work.

Gather changes — complete
Draft summary — cancelledDrafting stopped before the file was saved.
Review next steps — not started

API reference

AgentTodoList properties
Prop	Type	Default	Description
`title`required	`string`		Task plan name shown in the disclosure summary.
`items`required	`readonly TodoItem[]`		Ordered display-only tasks. Empty arrays render no panel.
`open`	`boolean`		Controls the disclosure state.
`defaultOpen`	`boolean`	`false`	Sets the initial disclosure state when uncontrolled.
`onOpenChange`	`(open: boolean, details?: unknown) => void`		Receives disclosure changes from the canonical Collapsible.
`...divProps`	`HTMLAttributes<HTMLDivElement>`		Native root attributes, including className and id.

TodoItem fields
Prop	Type	Description
`id`required	`string`	Stable key for the task row.
`label`required	`string`	Readable task text; long labels wrap.
`status`required	`pending \| active \| complete \| error \| cancelled`	Caller-owned display status. Only complete contributes to progress.
`description`	`string`	Optional task detail or failure reason.

AgentTodoList is the descriptive public name. TodoList is a compatibility export of the same implementation. Both import surfaces ship in the todo-list registry item. Item status also accepts error and cancelled; optional description stays caller-owned. Active rows compose Spinner; the summary composes Progress.Clock.