@jerryan/pi-todo-lite

A lightweight task tracker for the pi coding agent.

Design philosophy: intentional minimalism

The pi ecosystem already has capable task tracking extensions (rpiv-todo, @tintinweb/pi-tasks). This extension exists for a different user: someone who wants task tracking without the architectural weight.

What "lite" means

| Heavy approaches (rpiv-todo, pi-tasks) | pi-todo-lite | |---|---| | pending → in_progress → completed status machine | Boolean done — LLMs rarely explicitly mark tasks "in-progress" | | blockedBy dependency graphs with cycle detection | Dropped — LLMs execute tasks in order naturally | | Subagent execution, background process tracking | Not needed for most single-session work | | File-backed persistence with locking, shared lists | Session branch replay only — no external files | | i18n (8 locales) | English only | | owner, metadata, activeForm fields | Dropped — only subject + description | | 7 tools, 2000+ lines | 6 tools, ~1150 lines | | Massive prompt descriptions (Claude Code-style) | One-sentence descriptions, tight schemas |

What was kept (the good parts)

• Multi-tool design — todo_create, todo_update, todo_list, todo_get, todo_delete, todo_clear. Each has a tight schema with no dead-weight parameters.
• Persistent overlay widget — Shows pending tasks and recently completed tasks above the editor, filtered by completion order.
• Branch-aware replay — State stored in tool result details, reconstructed from the session branch on start/tree/compact. Forking and tree navigation always show the correct task list for that point in history.
• Custom TUI rendering — Compact renderCall/renderResult with status glyphs.
• /todos command — Quick user inspection grouped by pending/done.
• appendNote — Add paragraphs without replacing the full description.
• Periodic reminder — Injects a bookkeeping <system-reminder> when pending tasks have been idle past a token-usage threshold, nudging the agent to mark tasks done only if already completed during the conversation.

When to use this

• You want task tracking but don't want 7 tools competing for the LLM's attention.
• Your work fits in a single session and doesn't need cross-session persistence.
• You find in_progress states and dependency graphs create more ceremony than value.

When to use something else

• You need subagent execution or background process tracking → @tintinweb/pi-tasks
• You need shared task lists across multiple sessions → @tintinweb/pi-tasks
• You need full status machines, dependency graphs, or i18n → rpiv-todo

Install

pi install npm:@jerryan/pi-todo-lite

Or test directly:

pi -e ./extension.ts

Usage

The LLM can call the todo tools automatically. You can also prompt it explicitly:

"Track these tasks: refactor auth, update tests, deploy"

Reminder system

If pending tasks exist and no todo tool has been used for a while, a <system-reminder> nudge is injected to remind the agent that a task is still pending. It does not prompt the agent to start working on it — only to mark it done if it was already completed earlier in the conversation. The agent can otherwise ignore the reminder and continue its current focus.

Reminders are triggered by accumulated token usage, not by a fixed turn count.

Override the threshold with the environment variable:

PI_TODO_REMINDER_TOKENS=12000 pi -e ./extension.ts

User commands:

• /todos — Show all tasks grouped by status

Project structure

pi-todo-lite/
├── core.ts           # Pure logic — types, reducer, replay, formatting (no pi deps)
├── extension.ts      # Pi integration — widget, event handlers, tool/command reg
├── core.test.ts      # Vitest tests for the reducer
├── package.json
└── vitest.config.ts

Running tests

npm install
npm test

License

MIT