@timmyjl12/pi-todo

Persistent, visible todo tracking for the pi coding agent — Claude Code-style task tools, an above-editor widget, a statusline pill, and a /todo menu overlay.

The agent gets four tools it already knows from Claude Code (TaskCreate, TaskGet, TaskList, TaskUpdate) with dependency edges, and you get to see the plan live: a task list above the editor, counts in the footer, and a full-screen menu for hands-on management.

Todos (1/3)
◼ #2 Running the test suite
◻ #3 Ship the release › blocked by #2

Install

pi install npm:@timmyjl12/pi-todo

Or load directly for development:

pi -e ./index.ts

Tools

| Tool | Purpose | |---|---| | TaskCreate | Create a task with subject, description, optional activeForm, owner, metadata, and dependency edges. Starts pending. | | TaskGet | Full detail for one task — status, description, owner, all edges, metadata. | | TaskList | One line per task: #id [status] subject (owner) [blocked by #…], pending first. | | TaskUpdate | Change fields, status, edges, owner, metadata. status: "deleted" removes the task. |

→ Task #1 created successfully: Add repository layer with tests
→ #1 [pending] Add repository layer with tests
→ Updated task #1 status

Lifecycle: pending → in_progress → completed; status: "deleted" on update performs a hard delete (edges cleaned, ids never reused). Mark a task in_progress when you start it and completed the moment it's done — the tool descriptions coach the model on this.

Dependencies: addBlocks / addBlockedBy maintain both sides automatically. Cycles, self-references, and dangling ids are rejected with errors naming the offender, and a rejected update leaves no partial state.

The widget and the pill

• Above-editor widget — every task with a status glyph (✔ completed with strikethrough, ◼ in progress, ◻ pending), the active task's activeForm label, open blockers on pending rows, and a Todos (done/total) header. Past maxVisible rows it folds with +N more (M completed). An empty list renders nothing.
• Footer pill — ✓ 2/5 todos (or ◼ 1 active · 1/2 todos) via pi's keyed status API. Renders under pi-statusline and any footer that shows extension statuses; cleared on shutdown.

/todo command

A full-screen menu overlay (same pattern as the family's pickers): groups for Tasks, Actions (create, clear completed, clear all), and Settings, with / search, Tab group cycling, and inline task actions:

• s start · c complete · d delete — on the selected task
• Enter on Actions/Settings activates or cycles the value
• Esc backs out of search, then closes

Compact terminals (< 40 columns or < 16 rows) get a single-column fallback.

Storage

Tasks live in a JSON file with atomic writes (temp + rename with retry), keyed by scope:

| Scope | File | Behavior | |---|---|---| | session (default) | ~/.pi/agent/todo/sessions/<project>/<session-id>.json | Per-session; survives /reload and resume; new/forked sessions start fresh | | project | <workspace>/.pi/todo/tasks.json | Shared across sessions in the project | | global | ~/.pi/agent/todo/global.json | One list across projects | | memory | — | In-memory only; nothing written |

Ids are monotonic (highWaterMark) — never reused, even after the list empties and reopens. A session that ends with incomplete tasks leaves its file behind; session stores sweep sibling files untouched for 14+ days so dead sessions never accumulate. A corrupt store starts empty rather than crashing the session.

Configuration

Optional. Global defaults in ~/.pi/agent/pi-todo.json, project overrides in <workspace>/.pi/pi-todo.json (project wins key by key; the /todo Settings menu writes project overrides only). A missing or malformed file falls back to defaults.

{
  "scope": "session",
  "maxVisible": 10,
  "showAll": false,
  "autoClearCompleted": "never",
  "reminderTurns": null
}

| Setting | Values | Default | Behavior | |---|---|---|---| | scope | memory / session / project / global | session | Where task state lives (see Storage) | | maxVisible | 1–100 | 10 | Task rows before the +N more fold | | showAll | bool | false | Ignore maxVisible, show every task | | autoClearCompleted | never / on_list_complete | never | Clear completed tasks after the list finishes and a couple of idle turns pass | | reminderTurns | null / 1–200 | null | Inject a system-reminder nudging the model to call TaskList after this many turns without task-tool use |

Design boundaries

• No subagent execution (TaskExecute/TaskOutput/TaskStop) — agent orchestration belongs to pi-subagents / pi-fusion in this family; task tracking stays decoupled from it.
• No shared team lists — one writer per store; multi-session coordination over a single file is a locking surface deliberately left out.
• English only — no i18n layer.

Development

npm install
npm run typecheck
npm test

License

MIT — see LICENSE.