# pi-simple-todo

Minimal, Claude Code / opencode style todo-list tracking for the [Pi coding
agent](https://pi.dev). One tool, one active task at a time — nothing more.

## Why

Pi already ships an example todo extension, and there are richer community
options (dependency graphs, subagent orchestration, file-backed multi-session
stores). This package intentionally does none of that. It exists for the
common case: keep the agent honest about a plan during a single, longer task.

## What it does

- Registers a single tool, `todo_write`, which replaces the entire todo list
  on every call (`{ content, status }[]`, status is `pending` / `in_progress`
  / `completed`).
- Hard-enforces at most one `in_progress` item at a time — the strongest
  single lever against goal drift in agentic loops.
- Shows the current list live: a footer status (`☑ 1/3`) and a widget above
  the editor with `✓` / `▶` / `○` markers.
- Adds an ephemeral, Claude-Code-style `<system-reminder>` when the list has
  stalled (pending items exist but nothing is `in_progress`). The reminder is
  injected only into the outgoing model request, never written to the
  session file.
- Reconstructs state from the session branch (same pattern as Pi's bundled
  `examples/extensions/todo.ts`), so `/fork` and `/tree` navigation keep the
  right todo state for that point in history automatically.
- `/todos` command opens an interactive read-only overlay of the current
  list.

## What it deliberately does not do

- No `todo_read` tool — the live widget/status already show current state.
- No per-id CRUD, no dependency graph (`blockedBy`/`blocks`), no cycle
  detection.
- No file-backed store, no cross-session/multi-agent locking.
- No subagent execution or task orchestration.

If you need any of that, see `@tintinweb/pi-tasks` or `@juicesharp/rpiv-todo`.

## Install

```bash
pi install npm:@nilskluewer/pi-simple-todo
```

Project-local instead of global:

```bash
pi install npm:@nilskluewer/pi-simple-todo -l
```

Try without installing:

```bash
pi -e npm:@nilskluewer/pi-simple-todo
```

## Usage

Nothing to configure. Once active, the agent calls `todo_write` on its own
for multi-step tasks. You can also check progress any time with:

```
/todos
```

## License

MIT