pi-todo-lite
Pi todo extension: one ordered task table above the editor.
Package details
Install pi-todo-lite from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-todo-lite- Package
pi-todo-lite- Version
0.3.1- Published
- Nov 21, 2026
- Downloads
- 1,643/mo · 115/wk
- Author
- setwhite
- License
- MIT
- Types
- extension
- Size
- 52.9 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-todo-lite
简体中文 | English

The model keeps one ordered task table above the editor. The table replays after compaction, after a branch switch or after --continue. The package has no runtime dependencies.
Features
- The model side has one tool,
todo(tasks). The call submits the whole table and replaces the old table.tasks: []clears the table. - Pending tasks take lines first. If the table passes
ui.widget.maxLineslines, the rest collapse into+N more. alt+tcollapses the table and keeps the data.ui.*moves the table and changes the glyphs, the header and the completed style.- The extension adds four commands:
/todos,/todos clear,/todos export,/todos import <file>.
Install
pi install npm:pi-todo-lite
The old repository moved into this monorepo, so install from npm.
Configuration
The config file is <agent dir>/pi-todo/config.json. <agent dir> is $PI_CODING_AGENT_DIR, or ~/.pi/agent when unset. The directory is pi-todo, not the package name.
The extension only reads this file and never writes it. Without the file, all values are defaults.
An error names the absolute path and one path: reason line per fault. These cases throw: broken JSON, an unknown key, a wrong type, a wrong enum. An out-of-range number clamps to the bound.
Minimal configuration: zero config works. To make the table shorter, set ui.widget.maxLines. The default is 9 lines.
{
"ui": { "widget": { "maxLines": 5 } }
}
Full configuration: all keys follow, with their default values. // starts a comment; remove the comments in a real file.
{
"tools": { "todo": { "name": "todo" } }, // tool name
"plan": {
"maxTasks": 20, // max tasks per table. More fails the call
"maxSubjectChars": 120, // max characters per task
"requireSingleInProgress": false // true = only one in_progress task
},
"ui": {
"widget": {
"enabled": true, // show the widget
"maxLines": 9, // max lines (3–10)
"placement": "aboveEditor", // aboveEditor / belowEditor
"showCompleted": true, // list completed tasks individually
"header": "Todo {done}/{total} · {doing} doing", // header template: {done} {total} {doing}
"glyphs": { "pending": "[ ]", "inProgress": "[-]", "completed": "[x]" }, // per-status glyphs
"completedStyle": "strikethrough" // strikethrough / dim / plain
},
"shortcut": { "toggle": "alt+t" } // collapse key. off = don't register
},
"lifecycle": { "onFinish": "clear" }, // model / keep / clear
"commands": {
"todos": { "enabled": true }, // /todos
"export": {
"enabled": true, // /todos export
"dir": "", // output dir, empty = project root
"fileNamePattern": "todo-{timestamp}.md" // file name template. Never overwrites
},
"import": { "enabled": true } // /todos import <file>
},
"guidance": { // what the model sees. Per-key override, empty values included
"description": "…", // tool description. Empty = empty description
"promptSnippet": "", // the tool-list line. Empty = omitted (same as missing)
"promptGuidelines": ["…"] // guidelines. Empty array = omitted
}
}
An unknown key throws; no key is ignored silently.
Usage
A completed table stays on screen. The table clears when you send the next message. lifecycle.onFinish (model or keep) changes this behavior.
/todos export names the file after commands.export.fileNamePattern. On a name clash, /todos export yields and does not overwrite the file. /todos import <file> needs an empty table. Run /todos clear first.
/todos completes its arguments. Start typing clear, export or import and the list pops up. Press Tab to take the entry. After /todos import , the list shows the files and directories in the session directory. A directory ends with /. A path with spaces gets quotes.
Another extension may register /todos too, for example @ssk_dev/rpiv-todo-lean. Remove one of them. The tool name is configurable; the command name is not.
Docs
| Document | Content |
|---|---|
| ARCHITECTURE | Modules and dependency direction |
| GLOSSARY | Terms |
| Spec | Contract and acceptance criteria |
| Decisions | One file per decision |
| CHANGELOG.md | Release notes |
License
MIT © setwhite