131 lines
4.9 KiB
Markdown
131 lines
4.9 KiB
Markdown
# 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.
|
|
|
|
|
|
|
|
## 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`
|
|
- 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:
|
|
|
|
```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 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 and child IDs. |
|
|
|
|
Example append call:
|
|
|
|
```json
|
|
{
|
|
"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`.
|
|
|
|
## 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 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`:
|
|
|
|
```toml
|
|
[ui.sidebar.agents]
|
|
rows = [["state_icon", "workspace", "tab"], ["agent", "$ask", "$ask_count"], ["$task", "$task_count"]]
|
|
```
|
|
|
|
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
|