Initial release

2026-07-22 23:35:04 +08:00
commit 281f3c1615
17 changed files with 5001 additions and 0 deletions
@@ -0,0 +1,126 @@
+# pi-todo-herdr
+
+Hierarchical, session-local task tracking for [Pi](https://pi.dev), with atomic batch tools, a live task-tree widget, and optional [Herdr](https://herdr.dev) sidebar integration.
+
+![pi-todo-herdr task tree and Herdr sidebar](https://github.com/leset0ng/pi-todo-herdr/raw/main/media/screenshot.png)
+
+## Features
+
+- 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:
+
+```bash
+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:
+
+```bash
+pi -e npm:pi-todo-herdr
+```
+
+Update or remove it with Pi's package commands:
+
+```bash
+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:
+
+```json
+{
+  "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`.
+
+## Pi Widget
+
+The widget appears above Pi's editor while tasks exist. Run `/tasks` to hide or show it for the current Pi runtime.
+
+```text
+ 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 are compressed as `#7 Implement auth +2`.
+
+Add `$task` to the Herdr agent sidebar rows in `~/.config/herdr/config.toml`:
+
+```toml
+[ui.sidebar.agents]
+rows = [["state_icon", "workspace", "tab"], ["agent", "$ask"], ["$task"]]
+```
+
+Apply the change to a running Herdr server:
+
+```bash
+herdr server reload-config
+```
+
+Metadata failures never block task operations. The extension does not change Herdr's agent lifecycle or notification state.
+
+## Development
+
+```bash
+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