pi-xtodo

Task list for step-by-step agent work: blockedBy links (a DAG), persistent widget above the editor, TUI overlay, replay from history or save to disk.

Install

pi install npm:@xaccefy/pi-xtodo

Tool: todo

Action	Purpose
create	New task (subject needed); optional blockedBy, description, owner
update	Change fields / status / links (id needed)
list	Filter by status; includeDeleted for tombstones
get	Full detail including blockedBy / blocks
delete	Soft-delete (kept as a tombstone)
clear	Clear all tasks

Status lifecycle

pending ↔ in_progress → completed → deleted
                ↘ deleted

• completed → pending is not allowed (make a new task to reopen).
• Ids must be whole positive numbers ("1" works; "2.7" / "1e2" are rejected).

Dependencies

• blockedBy / addBlockedBy / removeBlockedBy form a DAG; cycles are rejected.
• Deleting a task (or update status: deleted) pulls its id out of every other task’s blockedBy, so dependents don’t hang on a tombstone.

Persistence

• Main copy: the session’s tool-result history (replay on session_start / compact / tree).
• If that’s empty, use the disk file ~/.pi/xtodo/<safe-session-id>.json.
• Session ids are cleaned so they can’t escape the folder.

Display

• A persistent widget above the editor shows the live list (Todos (done/total) header, tree rows, overflow collapses completed first). It auto-hides when no visible tasks remain and refreshes on every todo mutation, session_start, compact, and tree events.
• Tool results render as a one-line summary (glyph + first line / task count). Expand the tool row (app.tools.expand keybinding) to see full lists and details. Errors render as ✗ <message>.

Command

• /todos — overlay with the full list, grouped active → completed → deleted (esc/q/enter closes). Falls back to a notification when overlays are unavailable.

Development

bun test packages/pi-xtodo
bun run typecheck