pi-todos
Incremental session-native todo tracking for Pi with lifecycle actions, dependencies, replay, and a live overlay.
Package details
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
todotool with sequential, ID-based mutations. pending,in_progress,completed, and hiddendeletedtombstones.- 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
/todosfilters. - One balanced reconciliation reminder per user prompt when work remains open.
- Strict schemas and safe repair of legacy
update + statuscalls. - 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