@juicesharp/rpiv-todo

Give the model a task list you can see. rpiv-todo adds a todo tool, a /todos command, and a live panel above the editor to Pi Agent, so you always know what the agent is doing now, what it finished, and what is queued. The list is rebuilt from the conversation itself, so it survives /reload and compaction — useful on long research → design → implement sessions.

Install

pi install npm:@juicesharp/rpiv-todo

Restart your Pi session.

Quick start

Run /todos after the restart to confirm the extension is loaded. On a fresh session it prints:

No todos yet. Ask the agent to add some!

Then ask for something with several steps — "add a repository layer with tests, and track it as todos". The model calls todo and the panel appears above your input box, updating as work moves:

Press ctrl+shift+t to collapse the panel to its heading plus a one-line hint, and again to expand it. Run /todos at any time to print the full list grouped by status.

What you get

• The plan stays on screen. A panel above the editor shows every task with a status glyph, the label of whatever is in progress, and a Todos (done/total) heading — you never have to ask the agent where it is.
• Tasks survive /reload and compaction. Each tool call carries the full post-mutation snapshot, and the list is replayed from the session branch. No disk writes, nothing to lose.
• Finished work gets out of the way. Completed rows stay visible for the rest of the turn, then drop at the start of the next one; the panel disappears entirely when the list empties.
• The overlay never eats your terminal. Past the row budget it drops completed tasks first, truncates unfinished ones last, and tells you what it hid with +3 more (2 completed, 1 pending).
• The agent can sequence work, not just list it. blockedBy dependencies are validated before anything is written — dangling ids, deleted dependencies, self-blocks, and cycles are all rejected.
• Parallel sessions stay separate. Task state is keyed by session, so a detached or child session can neither read nor overwrite the foreground list.
• Localized UI, no setup required. Nine locales ship with the package and activate when @juicesharp/rpiv-i18n is installed; without it, everything falls back to English.

Configuration

Optional. Create ~/.config/rpiv-todo/config.json (or $XDG_CONFIG_HOME/rpiv-todo/config.json if you set that variable):

{
  "maxWidgetLines": 8,
  "collapseKey": "alt+t"
}

Setting	What it does	Default
maxWidgetLines	Content rows the overlay may use, heading included. Minimum 3. Applies on the next repaint.	12
collapseKey	Key that collapses and expands the panel, in Pi keybinding form (alt+o, ctrl+shift+t). Set "off" to register no shortcut. Needs /reload to rebind.	"ctrl+shift+t"
guidance	Replaces the built-in instructions the extension gives the model about when and how to use the todo list. Needs /reload.	(built-ins)

A missing or malformed file falls back to these defaults. rpiv-todo only reads this file — it never writes one. Full semantics: Configuration.

Reference

• todo tool reference — every todo parameter, the status machine, the response envelope, and the exact error strings.
• Configuration — config file resolution, option validation rules, and the accepted keybinding grammar.
• Overlay and /todos — overlay lifecycle, glyphs, overflow behavior, /todos output, and localization.

Requirements

• A Pi Agent host. No API key, no model selection, no native dependencies.
• An interactive session for the panel and /todos. Headless runs still get the todo tool; nothing is rendered.
• @juicesharp/rpiv-i18n is an optional peer — install it for a localized UI, skip it for English.

Related

• @juicesharp/rpiv-i18n (source) — localizes this extension's UI chrome and adds a /languages picker.
• @juicesharp/rpiv-pi (source) — the umbrella package that installs this extension alongside its siblings.

License

MIT — see LICENSE.