@timmyjl12/pi-todo

Persistent, visible todo tracking for the pi coding agent — Claude Code-style task tools (TaskCreate/TaskGet/TaskList/TaskUpdate) with dependency edges, an above-editor widget, a statusline pill, and a /todo menu overlay.

Packages

Package details

extension

Install @timmyjl12/pi-todo from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@timmyjl12/pi-todo
Package
@timmyjl12/pi-todo
Version
0.1.0
Published
Oct 8, 2026
Downloads
285/mo · 285/wk
Author
timmyjl12
License
MIT
Types
extension
Size
80.4 KB
Dependencies
0 dependencies · 5 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@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.