# Plan

> An agent's plan as a checklist that folds. A native Pyzed component for Python desktop GUIs, with a live preview, code examples and its API.

Source: https://albakore.github.io/pyzed/library/plan/

:::tip[In plain words]
A to-do list an AI assistant writes for itself and ticks off as it works.
:::

`ui.Plan` is a component that shows an AI agent's plan as a checklist: each step is pending (an empty circle), in progress (a dot, or a spinner with `running=True`) or done (a green check, with its text dimmed), and the header counts `done/total`. Clicking the header folds and unfolds the steps. `steps` are dicts with `step` (the text) and `status`: `"pending"`, `"in_progress"` or `"done"`.

`ui.Plan` · Category: [AI agents](https://albakore.github.io/pyzed/library/#ai-agents) · [Full reference →](https://albakore.github.io/pyzed/reference/ui/#plan)

**Code:**

```python
pz.container(ui.Plan(steps=[
    {"step": "Read the form and its handlers", "status": "done"},
    {"step": "Add the email field", "status": "done"},
    {"step": "Validate the email as you type", "status": "in_progress"},
    {"step": "Run the tests", "status": "pending"},
], running=True), width=420)
```

:::note[New]
This component was added recently. Tell us how it works for you in the [issue tracker](https://github.com/albakore/pyzed/issues).
:::

## When to use

- Above an agent's chat, while it works through a task of several steps.
- For any list of steps that updates as the work goes on, such as an install or a migration.

## Usage

```python
import pyzed as pz
from pyzed import ui

class Agent(pz.App):
    def __init__(self):
        self.steps = [{"step": "Add the form", "status": "done"},
                      {"step": "Wire the events", "status": "in_progress"}]
        self.working = True

    def view(self):
        return ui.Plan(steps=self.steps, running=self.working)
```

## Variants

:::note[About these captures]
Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site's theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open **Code** under a capture to see the snippet that draws it; free names such as `on_save` stand for your own callbacks.
:::

### State

Without `running` the step in progress shows a dot; folded is drawn as after a click on the header.

```python
pz.container(ui.Plan(steps=[{"step": "Add the form", "status": "done"},
                         {"step": "Wire the events", "status": "in_progress"},
                         {"step": "Run the tests", "status": "pending"}],
                  running=True), width=300)
```

```python
pz.container(ui.Plan(steps=[{"step": "Add the form", "status": "done"},
                         {"step": "Wire the events", "status": "in_progress"},
                         {"step": "Run the tests", "status": "pending"}]), width=300)
```

```python
pz.container(ui.Plan(steps=[{"step": "Add the form", "status": "pending"},
                         {"step": "Run the tests", "status": "pending"}]), width=300)
```

```python
pz.container(ui.Plan(steps=[{"step": "Add the form", "status": "done"},
                         {"step": "Run the tests", "status": "done"}]), width=300)
```

```python
pz.container(ui.Plan(steps=[{"step": "Add the form", "status": "done"},
                         {"step": "Run the tests", "status": "pending"}]), width=300)
```

## Events

Plan has no events of its own: it shows what you give it. Like every widget it also has the **18 common events** (`click`, `double_click`, `right_click`, `mouse_enter`, `drag`, `key_down`, `resize`…), attached with `.on(...)`: see [Events](https://albakore.github.io/pyzed/guides/events/) and [Events of every component](https://albakore.github.io/pyzed/library/events/).

It is a `pz.Component`, so it also raises `on_mount` and `on_unmount`, and its handlers get a `pz.Event` whose `value` holds the data.

## Properties and API

### `ui.Plan`

```python
class Plan
```

A component for an agent's plan: a checklist with `done/total` in its header, which folds it.

| Property | Default | Description |
| --- | --- | --- |
| `steps` | `None` | `{"step": text, "status": "pending" \| "in_progress" \| "done"}` dicts. |
| `running` | `False` | Spins the step in progress. |
| `theme` | `None` | Theme. |

[Full reference →](https://albakore.github.io/pyzed/reference/ui/#plan)

## Related

- [Tool call](https://albakore.github.io/pyzed/library/tool-call/): One step of an AI agent: what it did, its result, and Allow or Reject.
- [Progress](https://albakore.github.io/pyzed/library/progress/): A thin progress bar in a semantic color.
- [Edits bar](https://albakore.github.io/pyzed/library/edits-bar/): The files an agent changed, with Keep all and Reject all.