pi-todo-md

A shareable pi package that gives the agent a structured todo_md tool backed by a repo-local TODO.md file.

What it does

• manages TODO.md through a structured tool instead of ad-hoc file edits
• finds the nearest TODO.md in the current directory or a parent directory
• creates TODO.md at the git repo root when none exists yet
• keeps stable task IDs with hidden HTML comments
• writes a hidden file schema marker for future migrations
• supports sections, reordering, bulk add, rename, focus mode, priority metadata, notes, subtasks, check/uncheck, archive, and prioritize
• adds an interactive /todos [section] browser inside pi with keyboard actions
• injects a compact active-task summary into relevant agent turns so pi can stay aligned with the current working set

Install

From npm

pi install npm:pi-todo-md

From a local checkout

pi install /absolute/path/to/pi-todo-md -l

Quick start

After installing, start pi in your project and ask things like:

• Show me the current todo list
• Add a task to TODO.md to publish the plugin
• Add these tasks to TODO.md: write docs, record demo, publish package
• What should I work on next from TODO.md?
• Focus task #2 and show me the current focus list
• Mark task #3 as high priority
• Create an Inbox section and move task #5 there
• Rename task #2 to finish README polish
• Add a note to task #2 saying publish after the docs land
• Add subtasks to #2 for writing docs and publishing the package
• Mark task #2 as done
• Archive all completed tasks
• Move task #3 to In Progress
• Prioritize task #5
• /todos
• /todos In Progress

Tool API

The extension registers a tool named todo_md.

Action	Required	Optional	Description
list	—	section	Show the current task list
list_focused	—	—	Show the current focused tasks
next_task	—	section	Recommend the next open task
create_section	section	—	Create a new section
rename_section	section	targetSection	Rename a section
remove_section	section	targetSection	Remove a section, optionally moving its tasks
move_section	section, index	—	Reorder sections
add	text	section, index	Add one task
bulk_add	items	section, index	Add multiple tasks at once
check	id	—	Mark a task done
uncheck	id	—	Mark a task not done
rename	id, text	—	Change task text
focus_task	id	—	Mark a task as part of the active working set
unfocus_task	id	—	Remove a task from the active working set
set_priority	id, priority	—	Set priority to low, medium, or high
clear_priority	id	—	Remove priority metadata
set_note	id, text	—	Replace a task's note text
append_note	id, text	—	Append note line(s) to a task
clear_note	id	—	Remove all notes from a task
add_subtask	id, text	—	Add a subtask to a task
check_subtask	id, subtask	—	Mark a subtask done
uncheck_subtask	id, subtask	—	Mark a subtask not done
remove_subtask	id, subtask	—	Delete a subtask
archive_done	—	section	Move completed tasks into Archive
remove	id	—	Delete a task
move	id	section, index	Move a task to another section or position
prioritize	id	section	Move a task to the top of a section

There is also a /todos [section] command for an interactive view. Inside the browser you can use:

• ↑↓ or j/k to move
• x to toggle the selected task or subtask
• f to focus or unfocus the selected task
• h, m, l, or 0 to set high, medium, low, or no priority
• r to rename a task
• n to edit a task note
• s to add a subtask
• p to prioritize a task
• d to delete the selected task or subtask
• a to archive completed tasks
• o to toggle done items on and off

Managed file format

pi-todo-md normalizes TODO.md into a canonical format like this:

# TODO
<!-- pi-todo-md:schema=1 -->

## Tasks
- [ ] ship the plugin [focus] [high] <!-- pi-todo-md:id=1 -->
  - note: publish after trusted publishing works
  - [ ] write docs
  - [ ] publish package
- [x] read the docs <!-- pi-todo-md:id=2 -->

## In Progress
- [ ] package it for sharing <!-- pi-todo-md:id=3 -->

## Archive
- [x] initial release <!-- pi-todo-md:id=4 -->

The hidden <!-- pi-todo-md:schema=1 --> marker reserves room for future file migrations, and the hidden <!-- pi-todo-md:id=... --> markers keep task IDs stable across edits.

File placement rules

When the tool runs, it will:

1. use TODO.md in the current directory if present
2. otherwise walk up parent directories looking for TODO.md
3. if none exists, create one at the nearest git repo root
4. if not inside a git repo, create one in the current directory

Local development

Run the tests:

npm test

Preview the publish tarball:

npm pack --dry-run

Try the extension directly without installing it globally:

pi -e ./extensions/todo-md.js

Contributing

See CONTRIBUTING.md for:

• release conventions
• Release Please workflow details
• npm trusted publishing setup
• release debugging notes

License

MIT