Five focused tools: add_task, update_task, rm_task, list_task, and get_task
Parent/child task trees with generated, stable integer IDs
Atomic batch mutations: every requested change succeeds or none of it is applied
Four states: pending, in-progress, blocked, and done
Session-branch persistence across reload, resume, fork, and tree navigation
Compact Pi widget with hierarchy, status colors, and an adaptive progress bar
Optional Herdr metadata showing the current task in the agent sidebar

Requirements

Pi 0.81 or newer
Node.js 20 or newer
Herdr is optional; all task tools and the Pi widget work without it

Install

Install the latest version from npm:

pi install npm:pi-todo-herdr

Then start Pi. If Pi is already running, use /reload to load the extension.

To try the package for one run without installing it:

pi -e npm:pi-todo-herdr

Update or remove it with Pi's package commands:

pi update npm:pi-todo-herdr
pi remove npm:pi-todo-herdr

Usage

For complex work, Pi can create and maintain the task tree automatically. The extension adds one short prompt guideline encouraging task tracking for multi-step work without forcing it for trivial requests.

Tool	Parameters	Behavior
`add_task`	`{ tasks: [...] }`	Atomically adds multiple tasks. Nested `children` create descendants.
`update_task`	`{ tasks: [...] }`	Atomically patches multiple tasks. `parentId: null` moves to the root; `position` is a zero-based sibling index.
`rm_task`	`{ ids: [...] }`	Removes multiple tasks. Removing a parent cascades through its descendants.
`list_task`	`{}`	Returns the full tree as compact `id/status/name` lines.
`get_task`	`{ ids: [...] }`	Returns complete task details, including parent and child IDs.

Example add call:

{
  "tasks": [
    {
      "name": "Implement authentication",
      "description": "Add session validation and route protection.",
      "status": "in-progress",
      "children": [
        {
          "name": "Add auth middleware",
          "description": "Validate the session before protected handlers run."
        }
      ]
    }
  ]
}

Task IDs are generated by the extension and never reused within a session branch. Multiple tasks may be in-progress. A parent can be marked done only when all of its descendants are also done.

The widget appears above Pi's editor while tasks exist. Run /tasks to hide or show it for the current Pi runtime.

 Tasks 2/6 · !1  ━━━━━────────
  ◉ 1. Build auth
  ├─ ! 3. Resolve token issue
  └─ ○ 4. Add middleware
  ✓ 2. Define schema

Tool calls remain compact in the conversation. Expand a tool result with Pi's normal tool-output shortcut to inspect affected tasks or full descriptions.

Herdr Integration

When Pi runs inside Herdr, the extension reports the most specific in-progress task as a task pane metadata token. If nothing is in progress, it falls back to a blocked task. Parallel current tasks use a separate task_count token so Herdr can truncate long task names responsively while keeping the remaining count visible, for example #7 Implement auth · +2.

Add $task and $task_count to the same Herdr agent sidebar row in ~/.config/herdr/config.toml:

[ui.sidebar.agents]
rows = [["state_icon", "workspace", "tab"], ["agent", "$ask", "$ask_count"], ["$task", "$task_count"]]

Apply the change to a running Herdr server:

herdr server reload-config

Metadata failures never block task operations. The extension does not change Herdr's agent lifecycle or notification state.

Development

npm install
npm run typecheck
npm test
npm pack --dry-run

The package has no third-party runtime dependencies. Pi's runtime packages are declared as peers and supplied by Pi.

License

MIT

README.md

pi-todo-herdr

Features