pi-todo

A small todo tool for the pi coding agent. Replaces tintinweb/pi-manage-todo-list, which is a verbatim clone of GitHub Copilot's manage_todo_list.

Install: npm:@tian.zuo/pi-todo · npm package @tian.zuo/pi-todo · workspace packages/pi-todo

Why replace it

The Copilot clone spends ~565 tokens on every request: a 22-line description holding "When to use" (7 bullets), "When NOT to use" (3), a "CRITICAL workflow" (5 steps), and a "Todo states" block — plus ~180 tokens of parameter descriptions, and a ~30-token nag appended to every write result ("Ensure that you continue to use the todo list…").

The cause is structural: it defines no promptSnippet and no promptGuidelines, so behavioural policy had nowhere to go but the one field that ships inside the tool schema on every turn. It was written for a harness that has no such slots; pi has both.

| Concern | Copilot clone | pi-todo | |---|---|---| | capability | mixed into 22 policy-heavy lines | one 44-character description | | call contract | repeated prose | localized schema descriptions | | usage policy | mixed into the schema | two short promptGuidelines | | per-write nag | ~30 tokens | none | | metadata budget | unbounded | under 950 serialized characters, enforced by tests |

It also contradicted itself — the description says "Use this tool VERY frequently", then the write handler warns "Small todo list (<3 items). This task might not need a todo list."

What this one does

• One tool, todo, with write (replace the whole list) and read.
• Items are { id, title, status }. There is no per-item prose field: writes resend the entire list every time, so per-item descriptions are paid repeatedly and never shown.
• Statuses are unchanged from the tool it replaces — not-started, in-progress, completed — so lists in existing sessions still rebuild.
• The list renders through pi's own ctx.ui.setWidget above the editor. No bespoke widget component.
• /todos shows progress, /todos clear empties the list.

The one guard

write replaces the whole list, so a partial resend silently deletes items — no error, nothing in the transcript. Every write is compared against the previous list, and any unfinished item that disappeared is named in the result:

Todo list updated: 1/2 completed.
Warning: 1 unfinished item disappeared from this write and is now gone:
3. Update the changelog. write replaces the whole list, so resend every item
you still intend to do.

Pruning completed items is legitimate housekeeping and is never reported. Duplicate ids are rejected outright, since ids are how later writes address items.

State and branching

State lives in tool-result details, so branching, forking, and resuming rebuild the list belonging to that point in history. The session scanner also accepts results from the old manage_todo_list tool, so lists created before the switch survive.

Tests

pnpm --filter @tian.zuo/pi-todo test