# pi-session-todo

Session-local live todo checklists for the [Pi coding agent](https://pi.dev).

> Keep the agent on track and see how well it is progressing while it investigates, edits, tests, and ships multi-step work.

## Why use it?

Long agent runs can be hard to follow. The agent may skip a verification step, lose sight of the original goal, or spend several minutes working without giving you a useful indication of progress.

`pi-session-todo` gives the agent a visible execution contract:

- **Keeps work focused:** the agent breaks the task into concrete steps and is repeatedly reminded what remains.
- **Makes progress visible:** you can see what is pending, active, completed, or blocked without interrupting the run.
- **Shows execution quality:** the checklist gives you a quick view of whether the agent is advancing methodically, skipping steps, or getting stuck.
- **Makes intervention easier:** when priorities change, you can immediately see where the agent is and redirect it with context.
- **Separates intent from activity:** durable plans describe the approach; session todos show what is actually happening now.

It is not a substitute for reviewing the result, but it makes the agent's process much easier to supervise.

Todos belong to the current conversation—not to your repository or durable project plan.

## Features

- One `pi_todo` tool with `set`, `append`, `update`, `list`, and `clear` actions.
- Compact dim-grey progress status in Pi's footer.
- `/todo` overlay for the full checklist.
- Session persistence across restart and `/reload`.
- Branch-aware restoration after `/tree` navigation.
- Stable string IDs or convenient one-based indexes for updates.
- `pending`, `in_progress`, `done`, and `blocked` states with optional notes.
- Enforces at most one `in_progress` item.
- Migrates existing state from the original `project-workspaces-todos` entry.
- Works independently while integrating naturally with plan-mode extensions.

## Preview

A real Pi agent creates a three-step release plan, works through it, marks the active step, and checks off each result as it completes.

![pi-session-todo demo](https://raw.githubusercontent.com/kungfusaini/pi-session-todo/main/demo/pi-session-todo.gif)

## Install

```bash
pi install npm:pi-session-todo
```

Then restart Pi or run `/reload`.

Try it without installing:

```bash
pi -e npm:pi-session-todo
```

## Usage

The agent manages the checklist automatically for multi-step work. To inspect it yourself:

```text
/todo
```

Example tool call:

```json
{
  "action": "set",
  "items": [
    { "id": "inspect", "text": "Inspect the existing implementation", "status": "done" },
    { "id": "extract", "text": "Extract the standalone extension", "status": "in_progress" },
    { "id": "test", "text": "Run tests and package checks", "status": "pending" }
  ]
}
```

Update several items atomically:

```json
{
  "action": "update",
  "items": [
    { "id": "extract", "status": "done" },
    { "id": "test", "status": "in_progress" }
  ]
}
```

You can also update by one-based position:

```json
{ "action": "update", "id": "2", "status": "blocked", "note": "Waiting for credentials" }
```

## Todos vs. durable plans

`pi-session-todo` tracks **live execution progress** for the current conversation. A project plan tracks **intent and approach** across sessions. They complement each other:

- Change a todo as work advances.
- Change a durable plan only when scope, approach, risks, or completion criteria change.

The extension does not depend on a specific workspace or plan-mode package. Plan mode can enable `pi_todo` when installed.

## Development

```bash
git clone https://github.com/kungfusaini/pi-session-todo.git
cd pi-session-todo
npm install
npm run check
pi -e ./src/index.ts
```

Build the publish preview:

```bash
npm pack --dry-run
```

## Security and storage

The extension has no runtime dependencies beyond Pi's bundled peer packages and performs no network or filesystem operations. Todo checkpoints are stored as custom entries in Pi's existing session JSONL file and do not enter the model conversation context directly.

## License

[MIT](./LICENSE) © Sumeet Saini