pi-todos

Incremental session-native todo tracking for Pi with lifecycle actions, dependencies, replay, and a live overlay.

Packages

Package details

extension

Install pi-todos from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-todos
Package
pi-todos
Version
0.1.4
Published
Nov 19, 2026
Downloads
851/mo · 851/wk
Author
umbra2728
License
MIT
Types
extension
Size
77.7 KB
Dependencies
0 dependencies · 4 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

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

README

pi-todos

Incremental, session-native todo tracking for Pi. One todo tool, small lifecycle actions, no full-list rewrites, and no task files.

Why

Most todo extensions either replace the complete list on every update or expose a broad update call where models can forget the actual mutation. pi-todos uses dedicated lifecycle actions instead:

{ "action": "start", "id": 3 }
{ "action": "complete", "id": 3 }
{ "action": "reopen", "id": 3 }

Status changes need only an ID. Evidence and activity labels are optional. Updates never require the model to resend existing tasks.

Features

  • One todo tool with sequential, ID-based mutations.
  • pending, in_progress, completed, and hidden deleted tombstones.
  • Multiple active tasks with optional owners.
  • Atomic initial batch creation without replacing existing tasks.
  • Dependency validation with unresolved-start protection and cycle detection.
  • Optional completion evidence.
  • Session-branch operation journal instead of repeated full snapshots.
  • Reload, branch, resume, and compaction recovery with per-session isolation.
  • Live overlay with open tasks and three recent completed tasks.
  • Read-only /todos filters.
  • One balanced reconciliation reminder per user prompt when work remains open.
  • Strict schemas and safe repair of legacy update + status calls.
  • Structured results for codemode.

Install

Remove any extension that already owns the todo tool, then install pi-todos:

pi remove npm:@juicesharp/rpiv-todo
pi install npm:pi-todos

For local development:

pi -e /path/to/pi-todos

Existing tasks from other todo extensions are not migrated.

Tool actions

Create

One task:

{
  "action": "create",
  "subject": "Inspect the implementation",
  "description": "Read the reducer and replay logic",
  "owner": "researcher"
}

An initial batch:

{
  "action": "create",
  "tasks": [
    { "subject": "Inspect the implementation" },
    { "subject": "Implement incremental updates" },
    { "subject": "Verify the behavior" }
  ]
}

Batch creation is atomic and appends tasks. It never replaces the current list. Batch items may depend on existing tasks or earlier items in the same batch; forward and self references are rejected. title/content, active_form, and dependsOn are normalized to subject, activeForm, and blockedBy. Model-assigned IDs are ignored.

Start, complete, and reopen

{ "action": "start", "id": 1, "activeForm": "inspecting the implementation" }
{ "action": "complete", "id": 1, "evidence": "npm test: 42 passed" }
{ "action": "reopen", "id": 1 }

activeForm and evidence are optional. Transitions are tolerant and exact retries return No change. Starting a task with unresolved dependencies returns an error.

Update fields

{
  "action": "update",
  "id": 2,
  "description": "Updated acceptance criteria",
  "addBlockedBy": [1]
}

Mutable fields are subject, description, activeForm, owner, evidence, addBlockedBy, and removeBlockedBy. Pass null to clear an optional text field. Status is changed only through lifecycle actions.

List and inspect

{ "action": "list" }
{ "action": "list", "status": "completed", "completedLimit": 10 }
{ "action": "list", "status": "all" }
{ "action": "get", "id": 2 }

The default list and status: "all" contain open tasks and the three most recently completed tasks; all also includes deleted tasks. completedLimit applies only to status: "completed", so older history is never sent to the model unless it explicitly asks for completed tasks. When completed tasks are hidden, the result ends with a +N older completed hidden note.

Delete and clear

{ "action": "delete", "id": 2 }
{ "action": "clear_completed" }
{ "action": "clear_all" }

delete creates a tombstone. clear_completed physically prunes completed tasks and their dependency edges without resetting IDs. clear_all removes all tasks and resets IDs.

Overlay and command

The overlay shows open tasks and three recent completed tasks within a bounded row budget.

/todos is read-only:

/todos
/todos open
/todos pending
/todos in_progress
/todos completed 20
/todos deleted
/todos all

With no arguments, /todos shows all non-deleted tasks grouped by status.

Reminders

After session restoration or compaction, the next model request receives one compact list of open tasks.

If the agent tries to finish with open tasks, the extension requests one reconciliation continuation per genuine user prompt. The reminder already contains the open tasks and the three most recently completed tasks, so the agent does not need to call list. The reminder explicitly allows intentional pauses for user questions, waiting for input, or background work; otherwise, the agent should continue and finish the remaining work. There is no repeated autonomous loop.

Configuration

No configuration is required. Optional JSON lives at ~/.pi/agent/pi-todos.json:

{
  "completedInList": 3,
  "completedInOverlay": 3,
  "maxOverlayLines": 12,
  "settleReminder": true
}

Changes are read when needed. Invalid values fall back to defaults with a warning.

Development

Requires Node >=22.19.0.

npm ci
npm run check

The check suite runs TypeScript, node:test, no-comment validation, and npm pack --dry-run. TypeScript ships directly; there is no build step.

See CONCEPT.md for the complete design and acceptance criteria.

Releasing

Releases use GitHub Actions and npm Trusted Publishing with provenance:

npm version patch
git push --follow-tags

The tag must match package.json. The workflow runs all checks, publishes to npm, and creates a GitHub Release.

License

MIT