pi-todo

简体中文

A Todo extension for Pi, maintained from @juicesharp/rpiv-todo. It registers the todo tool, the /todos command, and a persistent task overlay. It can be installed on its own and is also included in the aggregate @zhcsyncer/pi-extensions package.

This fork intentionally does not integrate tool intent. Successful Todo calls render as zero rows in the TUI transcript by default because the persistent widget already shows current state. Press Ctrl+O to expand compact call and result summaries; execution errors always remain visible. Tool content and versioned state details remain in the session, preserving model feedback, branch restoration, and reconstruction after reload.

Install

Install only the Todo extension:

pi install npm:@zhcsyncer/pi-todo

Or install the complete extension bundle from this repository:

pi install git:github.com/zhcsyncer/pi-extensions

Workflow and state contract

• Execute single-step, low-risk work directly. Todos represent independently valuable milestones in multi-stage work.
• The normal lifecycle is pending → in_progress → completed. A pending task may move directly to completed when reconciling work already finished, and an active task may return to pending when separate blocker work is required.
• Create defaults to pending, or pass status: "in_progress" to start immediately. subject and optional description identify the task; there is no separate active-form field.
• Exactly one task may be in_progress. A task whose dependencies are incomplete cannot start or complete.
• batch applies create/update/delete operations in array order and rolls the entire batch back if any operation fails. Complete or re-queue the active task before starting the next one.

Create an initial list and start the first milestone atomically:

{
  "action": "batch",
  "operations": [
    { "action": "create", "subject": "Research current behavior", "status": "in_progress" },
    { "action": "create", "subject": "Implement changes" },
    { "action": "create", "subject": "Validate results" }
  ]
}

Hand off an existing list in operation order:

{
  "action": "batch",
  "operations": [
    { "action": "update", "id": 1, "status": "completed" },
    { "action": "update", "id": 2, "status": "in_progress" }
  ]
}

Configuration and status icons

Global configuration lives at:

$PI_CODING_AGENT_DIR/extension-data/pi-todo/config.json

Pi's default agent directory makes this ~/.pi/agent/extension-data/pi-todo/config.json. On first read, an existing $XDG_CONFIG_HOME/rpiv-todo/config.json (normally ~/.config/rpiv-todo/config.json) is migrated atomically. The canonical file always wins; malformed, unreadable, or conflicting legacy files are retained with a warning rather than overwritten or silently removed.

Select a status-icon preset with statusIcons:

{
  "statusIcons": "ascii"
}

Preset	Heading	pending	in_progress	completed	Notes
ascii (default)	[T]	[ ]	[>]	[x]	Fixed-width ASCII; the most portable option across terminals
unicode	≡	○	◉	✓	Compact standard Unicode glyphs
nerd-font	󰝖	󰄰	󰪞…󰪥	󰗠	Requires a Nerd Font; only active task rows animate at 300 ms intervals

The heading always uses its own static Todo icon. Status glyphs use Pi theme semantics: pending is dim, in progress is accent, and completed is success. Task text further distinguishes state: pending is muted, in progress is bold accent, and completed is struck-through dim. /todos is a one-shot notification and uses the static middle frame 󰪡 for Nerd Font mode.

The same file may set guidance.promptSnippet and guidance.promptGuidelines to override model-facing Todo guidance. Invalid icon or guidance values retain the existing fallback behavior.

Legacy session snapshots may still contain activeForm; replay ignores that retired field, and new schemas and snapshots no longer emit it.

Provenance

• Upstream: juicesharp/rpiv-mono
• Baseline: v1.20.0 / 060373d9292aeb46aeedc23a6d818a997200a6e5
• Preserved upstream documentation: UPSTREAM_README.md
• Preserved upstream history: UPSTREAM_CHANGELOG.md

This package is published independently as @zhcsyncer/pi-todo; the root bundle embeds the same implementation.

Rendering and persistence

• renderShell: "self" hides successful nodes by default and provides an auditable expanded summary without duplicating the widget.
• Reducer validation failures throw real Pi tool errors; execution errors are always visible.
• Every tool result stores a schema-versioned tasks and nextId snapshot in details.
• session_start, session_tree, and session_compact restore the last valid Todo snapshot on the active branch.
• Each extension runtime owns an isolated store, so multiple SDK AgentSessions in one Node.js process do not share tasks.
• Raw tool calls and results remain in the session; default hiding affects only the TUI.
• Task history remains session state. Only user-editable display and guidance configuration moved to extension-data/pi-todo/config.json.

Development

pnpm --filter @zhcsyncer/pi-todo check
pi --no-extensions -e ./packages/pi-todo --list-models __pi_todo_check__

License

MIT. See LICENSE and UPSTREAM_LICENSE.