@raoxxxwq/pi-tasks

A pi extension that brings Claude Code-style task tracking and coordination to pi. Track multi-step work with structured tasks, dependency management, and a persistent visual widget.

Status: Early release.

Features

• 4 LLM-callable tools — TaskCreate, TaskList, TaskGet, TaskUpdate
• Persistent widget — live task list above the editor with ✔ / ◼ / ◻ status icons, task numbers, and an active spinner for in-progress work
• System-reminder injection — periodic <system-reminder> nudges when task tools have not been used recently
• Dependency management — bidirectional blocks / blockedBy relationships with warnings for cycles, self-deps, and dangling references
• Shared task lists — multiple pi sessions can share a file-backed task list for coordination
• File locking — concurrent access is safe when multiple sessions share a task list
• Auto-clear completed tasks — optional delayed cleanup for completed work

Install

pi install npm:@raoxxxwq/pi-tasks

Or load directly for development:

pi -e ./src/index.ts

Widget

The extension renders a persistent widget above the editor:

● 4 tasks (1 done, 1 in progress, 2 open)
  ✔ #1 Design the flux capacitor
  ✳ #2 Acquiring plutonium... (2m 49s · ↑ 4.1k ↓ 1.2k)
  ◻ #3 Install flux capacitor in DeLorean › blocked by #1
  ◻ #4 Test time travel at 88 mph › blocked by #2, #3

| Icon | Meaning | |------|---------| | ✔ | Completed (strikethrough + dim) | | ◼ | In-progress (not actively executing) | | ◻ | Pending | | ✳ / ✽ | Active in-progress task (shows activeForm, elapsed time, token counts) |

Widget display settings

How tasks are sorted and how many are shown can be configured via /tasks -> Settings (saved to .pi/tasks-config.json).

| Setting | Values | Default | Behaviour | |---------|--------|---------|-----------| | sortOrder | id / status / recent / oldest | id | id = creation order; status groups completed -> in-progress -> pending; recent / oldest = by last-updated time | | maxVisible | 5-100 | 10 | Caps how many task lines the widget shows (ignored when showAll is on) | | showAll | true / false | false | When true, every task is shown regardless of maxVisible | | hiddenAt | bottom / top | bottom | When the list overflows maxVisible, where the ... and N more collapse happens |

Note: the widget's status order is completed-first, which is the reverse of the TaskList tool's pending-first order.

Tools

TaskCreate

Create a structured task. Used proactively for complex multi-step work.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | subject | string | yes | Brief imperative title | | description | string | yes | Detailed context and acceptance criteria | | activeForm | string | no | Present continuous form for spinner (for example, Running tests) | | metadata | object | no | Arbitrary key-value pairs |

TaskList

List all tasks with status, owner, and blocked-by info.

Sort order: pending first, then in-progress, then completed (each group by ID).

TaskGet

Get full details for a specific task.

Shows owner (if set) and open (non-completed) dependency edges. Non-empty metadata is displayed as JSON.

TaskUpdate

Update task fields, status, metadata, and dependencies.

| Parameter | Type | Description | |-----------|------|-------------| | taskId | string | Task ID (required) | | status | pending / in_progress / completed / deleted | New status | | subject | string | New title | | description | string | New description | | activeForm | string | Spinner text | | owner | string | Owner or assignee label | | metadata | object | Shallow merge (null values delete keys) | | addBlocks | string[] | Task IDs this task blocks | | addBlockedBy | string[] | Task IDs that block this task |

Setting status: "deleted" permanently removes the task.

Task Lifecycle

pending -> in_progress -> completed
                     -> deleted (permanently removed)

Tasks are created as pending. Mark in_progress before starting work, completed when done. deleted removes entirely and IDs never reset.

Dependency Management

• Bidirectional edges — addBlocks / addBlockedBy maintain both sides automatically
• Dependency warnings — cycles, self-dependencies, and references to non-existent tasks are stored but produce warnings in tool responses
• Display-time filtering — TaskList only shows non-completed blockers in [blocked by ...]
• Raw data preserved — TaskGet shows all edges, including completed blockers
• Cleanup on deletion — removing a task cleans up all edges pointing to it

Task Storage

Task storage is controlled by the taskScope setting (/tasks -> Settings -> Task storage):

| Mode | File | Behaviour | |------|------|-----------| | memory | (none) | In-memory only — tasks lost when session ends | | session (default) | <cwd>/.pi/tasks/tasks-<sessionId>.json | Per-session file — isolated between sessions, survives resume | | project | <cwd>/.pi/tasks/tasks.json | Shared across all sessions in the project |

On new session start, if all persisted tasks are completed they are auto-cleared for a clean slate. On session resume, all tasks (including completed) are shown so the user can review progress. Empty session files are automatically deleted when all tasks are cleared.

Auto-clear completed tasks

The autoClearCompleted setting controls automatic cleanup of completed tasks:

| Mode | Behaviour | |------|-----------| | never | Completed tasks stay visible until manually cleared via /tasks -> Clear completed | | on_list_complete (default) | Cleared after all tasks are done and a few idle turns pass | | on_task_complete | Each completed task is cleared individually after a few turns |

Both auto-clear modes use a turn-based delay for non-jarring UX.

Settings (taskScope, autoClearCompleted, sortOrder, maxVisible, showAll, hiddenAt) are saved to <cwd>/.pi/tasks-config.json.

Override via environment variables

| Variable | Value | Behaviour | |----------|-------|-----------| | PI_TASKS | off | In-memory only (CI / automation) | | PI_TASKS | sprint-1 | Named shared list at ~/.pi/tasks/sprint-1.json | | PI_TASKS | /abs/path/tasks.json | Explicit absolute file path | | PI_TASKS | ./tasks.json | Relative path resolved from cwd | | (unset) | | Uses taskScope setting (default: session) | | PI_TASKS_DEBUG | 1 | Trace extension debug logs to stderr |

Named and explicit paths use a file-locked store with stale-lock detection.

/tasks Command

Interactive menu:

Tasks
├─ View all tasks (4)
├─ Create task
├─ Clear completed (1)
├─ Clear all (4)
└─ Settings

• View all tasks — select a task to see details and take actions (start, complete, delete)
• Create task — input prompts for subject and description
• Clear completed — remove all completed tasks
• Clear all — remove all tasks regardless of status
• Settings — configure task storage, auto-clear completed tasks, and widget display settings

Architecture

src/
├── index.ts            # Extension entry: 4 tools + /tasks command + widget
├── types.ts            # Task and store data types
├── task-store.ts       # File-backed store with CRUD, dependencies, locking
├── auto-clear.ts       # Turn-based auto-clearing of completed tasks
├── reminder-cadence.ts # Reminder cadence logic
├── tasks-config.ts     # Config persistence -> .pi/tasks-config.json
└── ui/
    ├── task-widget.ts    # Persistent widget with status icons and spinner
    └── settings-menu.ts  # /tasks -> Settings panel

Development

npm install
npm run typecheck
npm test
npm run build

License

MIT — tintinweb