pi-todo

Persistent per-project todo tracker with a live TUI widget for Pi.

What It Does

• Registers a todo tool the LLM can call to manage a task list
• Stores tasks in .pi/todo.json in the project root (per-project, persistent)
• Shows a live widget above the editor with the current todo state
• Auto-loads existing todos on session start

Installation

Add the extension path to ~/.pi/agent/settings.json:

{
  "extensions": ["~/.pi/agent/extensions/todo/src/index.ts"]
}

Or if you already have extensions:

{
  "extensions": ["~/.pi/agent/extensions/todo/src/index.ts", "other/extension/path"]
}

Then restart Pi (or run /reload).

Tool: todo

Actions

Action	Required Fields	Description
add	text	Create a new todo item
update	id	Modify an item's text/status/priority/assignee/blockedBy
toggle	id	Cycle status: pending → in-progress → done → pending
remove	id	Delete an item
list	—	List all items (optional: filter)
clear	—	Remove all completed items
reorder	id, direction	Move an item up or down in the list

Parameters

Field	Type	Required	Description
action	string	yes	One of: add, update, toggle, remove, list, clear, reorder
id	string	conditional	Task ID (e.g. T-001)
text	string	conditional	Task description
status	string	no	pending, in-progress, done, blocked
priority	string	no	low, medium, high, critical (default: medium)
assignee	string	no	Who's doing it
filter	string	no	Filter for list: all, pending, in-progress, done, blocked
blockedBy	string	no	Task ID this is blocked by
direction	string	no	Reorder direction: up or down

Examples

todo({ action: "add", text: "Build StorefrontController", priority: "high", assignee: "Ultron" })
todo({ action: "toggle", id: "T-001" })
todo({ action: "list", filter: "pending" })
todo({ action: "reorder", id: "T-003", direction: "up" })
todo({ action: "clear" })

Slash Commands

• /todo — List all todo items
• /todo clear — Clear completed items

Storage

Tasks are stored in .pi/todo.json in the project root:

{
  "items": [
    {
      "id": "T-001",
      "text": "Build StorefrontController",
      "status": "in-progress",
      "priority": "high",
      "assignee": "Ultron",
      "createdAt": "2026-07-05T19:02:00Z",
      "updatedAt": "2026-07-05T19:02:00Z",
      "blockedBy": null
    }
  ],
  "counter": 1
}

Widget

The live widget appears above the editor with a green border and shows:

┌──────────────────────────────────────────────────┐
│ TODO · 3 tasks                                    │
│   2 pending · 1 active                            │
│   [ ] T-001 [HIGH] Build StorefrontController · Ultron │
│   [ ] T-002 [MED]  Port landing.html · Maya       │
│   [•] T-003 [LOW]  Verify storefront routes · Quinn │
└──────────────────────────────────────────────────┘

Status icons: [ ] pending, [•] in-progress, [x] done, [!] blocked

Changelog

v1.2.0

• ASCII status icons — Replaced emoji status icons with ASCII equivalents ([ ], [•], [x], [!]) for universal terminal compatibility and cleaner rendering.
• Removed clipboard emoji from widget header.

v1.1.0

• Bordered widget — The live widget now renders inside a green Unicode box border (uses theme.fg("success")) for better visual separation from the chat area.

v1.0.0

• Initial release: todo tool, live widget, slash commands, per-project persistence.

Design Decisions

• Per-project, not global — Each project has its own todo list
• Main agent only — Subagents cannot call the todo tool
• Auto-generated IDs — T-001, T-002, T-003...
• Synchronous file I/O — Avoids race conditions (Node single-threaded)
• No external dependencies — Uses only Pi's built-in typebox