pi-todo

Phased todo lists for pi — the oh-my-pi todo tool migrated to a pi extension.

The agent gets a todo tool: a phased task list (phases → tasks with lifecycle statuses) persisted with the session. You get a /todo command and a todo_updated event other extensions can consume (pi-goal uses it to attach live progress state to goal continuations).

The extension is a cognitive-neutral notepad: statuses change only through explicit ops, and none of the omp behavior-engineering survives — no system-prompt nudges, no stop-time nag loop, no hidden reminders. The list records state; it never steers the agent.

Install

pi install npm:@fyeeme/pi-todo

No configuration, no settings, no flags — installed means active. Works in TUI, RPC, and headless (-p) modes.

The tool

Nine operations over phases: [{ phase, items: string[] }] state:

op	Fields	Effect
init	list (or flat items)	Replace the whole list; all tasks start pending
start	task	Mark in_progress (explicit; other tasks untouched)
done	task or phase	Mark completed
drop	task or phase	Mark abandoned (never deleted)
block	task or phase, reason?	Park open work awaiting external input; one-line reason
unblock	task or phase	blocked → pending, clears the note
rm	task? or phase?	Remove a task / clear a phase / clear everything
append	phase, items	Add pending tasks; lazily creates the phase
view	—	Read-only snapshot

Semantics ported from oh-my-pi: batch-atomic duplicate rejection (a failing op applies nothing), block never reopens finished work, view never writes. Deliberate deviation: the single-in_progress invariant and the auto-promotion pointer are removed — statuses are set only by explicit ops, and multiple in_progress tasks are allowed.

Command

The full oh-my-pi /todo verb set:

/todo                              Show current todos (Markdown checklist)
/todo edit                         Round-trip todos through the editor
/todo copy                         Print todos as Markdown
/todo export [<path>]              Write todos to file (default: TODO.md)
/todo import [<path>]              Replace todos from file (default: TODO.md)
/todo append [<phase>] <task...>   Append a task; phase fuzzy-matched or auto-created
/todo start  <task>                Mark task in_progress (fuzzy match)
/todo done   [<task|phase>]        Mark task/phase/all completed
/todo drop   [<task|phase>]        Mark task/phase/all abandoned
/todo rm     [<task|phase>]        Remove task/phase/all

Event contract

After every successful mutation:

pi.events.emit("todo_updated", { phases }); // full snapshot; never on view/failure

pi-goal integration

pi-goal embeds a <todo_context> block into its per-turn goal context when the todo tool is active and the list is non-empty — live progress state for autonomous goal continuations. pi-todo is fully usable without pi-goal; pi-goal degrades silently without pi-todo.

Persistence

Every mutation appends a full todo-phases snapshot entry to the session. On session start (resume/fork/tree navigation/reload), the latest valid snapshot on the current branch wins, so navigating the session tree restores the todo state of that point in history. Malformed entries are skipped, never fatal.

Ported from oh-my-pi — what was dropped

Source: oh-my-pi/packages/coding-agent/src/tools/todo.ts (plus reminder, slash-command helpers, prompts). Behavior semantics are ported verbatim; host-internal surfaces with no pi counterpart are not:

omp surface	Status in pi-todo
mid-run todo nudge (tool-choice queue)	Dropped — omp host-internal
eager-todo / prewalk system-prompt arming	Dropped — cognitive-neutral refactor (no prompt steering)
Stop-reminder loop (checkCompletion, ×3 nag)	Dropped — cognitive-neutral refactor (no auto-continuation)
Manual-edit <system-reminder> injection	Dropped — cognitive-neutral refactor
Single in_progress invariant / auto-promotion pointer	Dropped — statuses are explicit-only
/todo edit + markdown round-trip	Kept — via ctx.ui.editor
Sticky HUD / collapsed viewport / animations	Kept (viewport) in the transcript renderer; HUD dropped
Subagent todo-match lighting	Dropped — no subagent HUD contract
todo.enabled settings gate	Dropped — no settings API by design: installed means active

Development

npm run typecheck   # from packages/extensions/pi-todo
npm run test        # vitest

License: MIT