pi-todo.txt

Pi extension for tracking multi-step work as standard todo.txt entries.

Install

pi install npm:pi-todo.txt

Or from the GitLab repository:

pi install git:gitlab.com/jarkkojs/pi-todo.txt

Tool

The model-facing todo tool stores the task list as todo.txt in the working directory. It supports create, update, complete, list, and delete. todo.txt is the source of truth. Every action processes the file first: it re-reads todo.txt, adopts entries added outside the session, drops tasks the file no longer lists, repairs broken lines (lowercase priority, x without a date, blank and comment lines), applies the action, and writes the list back atomically. The file is watched while the session runs, so an editor, !rm todo.txt, or another agent is mirrored into the list within a moment: deleting the file empties it. Tasks keep their id as long as a matching line survives. The file is never created in a project that does not already have one until the first task exists.

Snapshots are also stored in Pi session history, so branch navigation and reloads restore the corresponding list. After compaction, the extension restores the current state to agent context as hidden, explicitly structured task data so progress is not lost or mistaken for new instructions. The list stays off screen until you open it with /todo.txt.

Each entry is one line with optional priority (A)-(Z) at the start, optional creation date, +project tags, @context tags, and key:value metadata such as due:YYYY-MM-DD. Completed tasks are written as x YYYY-MM-DD ...; completion preserves priority as pri:A.

Command

/todo.txt slides a full-width pane up from the bottom of the terminal, showing tasks with priorities, +project tags, @context tags, and key:value metadata. Use the arrow keys to move the cursor and Space to select tasks (shown with a ✓ mark). Press a to add a free-form todo.txt line, or e to edit the entry under the cursor. Both prompts validate the line with the same rules as the tool before accepting it. Press Enter to open an implementation confirmation, then Enter again to implement the selected tasks (or the task under the cursor when none are selected). Press Ctrl+D to open the equivalent deletion confirmation. Press c to confirm removal of completed entries; tasks completed or added after the prompt remain.

The pane updates todo.txt on open and after every add, edit, and delete. External changes are picked up automatically while the session runs, including when a filesystem watch event is missed. Each write sorts open tasks by priority with completed tasks last, and completing a prioritized task uses the todo.txt pri:A metadata convention to preserve its former priority.

Development

npm install
npm run all

Scripts:

Release:

./scripts/release.sh <next-version>

License

Apache-2.0. See LICENSE.