pi-todo-herdr

Hierarchical, session-local task tracking for Pi, with atomic batch tools, a live task-tree widget, and optional Herdr sidebar integration.

Features

• Five focused tools: set_tasks, update_task, rm_task, list_task, and get_task
• Parent/child task trees with generated integer IDs and atomic append/replace modes
• Atomic batch mutations: every requested change succeeds or none of it is applied
• Four states: pending, in-progress, blocked, and done
• Cumulative active-time tracking that pauses outside in-progress and survives session restore
• Session-branch persistence across reload, resume, fork, tree navigation, and context compaction
• A concise first-action workflow prompt plus a one-shot post-compaction recovery reminder
• 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 large, multi-stage work, the extension instructs Pi to call set_tasks before exploration as the only tool in the first batch. Smaller work remains untracked. Pi then updates task states at each real transition instead of reconstructing progress at the end.

After automatic or manual context compaction, the extension sends one short hidden reminder only when unfinished tasks exist. Pi calls list_task to recover the authoritative current IDs and statuses; the full tree is not injected on every model call.

Tool	Parameters	Behavior
set_tasks	{ mode, tasks, force? }	append extends the tree; replace atomically installs a new tree or clears it with []. Replacing unfinished work requires force: true.
update_task	{ tasks: [...] }	Atomically patches multiple tasks. parentId: null moves to the root; position is a zero-based sibling index.
rm_task	{ ids: [...], reason }	Removes only mistaken, duplicate, or canceled 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/child IDs and timing for tasks that have started.

Example append call:

{
  "mode": "append",
  "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."
        }
      ]
    }
  ]
}

Descriptions are optional, but useful scope, constraints, and done criteria improve recovery through get_task. IDs are not reused by append/remove operations; replace deliberately rebuilds IDs from 1. Replace forbids parentId, so new hierarchy must use nested children. Multiple tasks may be in-progress. A parent can be marked done only when all descendants are also done.

A task starts timing the first time it enters in-progress. Leaving that state records a stop and pauses the timer; entering it again resumes with a new active segment while preserving the cumulative duration. Repeated updates with the same status, as well as name, description, hierarchy, and position changes, do not reset timing. For started tasks, get_task includes the first startedAt timestamp, a stoppedAt timestamp while paused, and cumulative durationMs. Timestamps use ISO 8601.

Pi Widget

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 · 12:08
  ├─ ! 3. Resolve token issue · 03:41
  └─ ○ 4. Add middleware
  ✓ 2. Define schema · 04:31

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