pi-tasks

A maintained fork of tintinweb/pi-tasks, based on v0.7.2. It gives Pi a Claude Code-style task list and visible progress widget while leaving worker execution and process lifecycle to Pi's native harnesses and external orchestrators such as Herdr.

What this fork keeps

• TaskCreate, TaskList, TaskGet, and TaskUpdate
• the persistent above-editor widget with active-task animation, elapsed time, and token usage
• session, project, or in-memory task persistence
• dependency tracking with blocks and blockedBy
• bounded task reminders injected into model context
• the interactive /tasks menu
• locked file-backed stores for concurrent sessions
• a versioned pi-tasks:state event for Advisor and orchestration adapters
• a pi-advisor:abandon-unverified-task listener so Advisor can close hanging tasks after a missing-evidence complete without mutating the store itself

Ownership boundary

This extension records task truth. It does not launch, stop, or monitor processes or subagents.

The upstream TaskOutput, TaskStop, TaskExecute, subagent RPC, and auto-cascade paths are intentionally removed. Pi's native harness or Herdr owns worker creation and lifecycle, while Advisor may reject only an agent's unsupported attempt to mark a task complete. After that reject, Advisor may ask this extension to delete the still-open task if the agent settled without evidence.

Install

Pin the Git commit in Pi settings:

{
  "packages": [
    "git:github.com/shawnhamby/pi-tasks@<commit>"
  ]
}

For local development:

pi -e ./src/index.ts

Tools

• TaskCreate creates a pending task with a subject, description, optional active form, and metadata.
• TaskList lists pending, active, completed, and blocked work.
• TaskGet returns one task's full description, ownership, metadata, and dependencies.
• TaskUpdate changes status, details, ownership, metadata, and dependency edges.

The normal lifecycle is pending -> in_progress -> completed. deleted removes a task.

Widget and storage

The widget appears above the editor and stays compact by default. Configure it through /tasks -> Settings.

Task storage defaults to one file per Pi session outside the repository:

~/.pi/agent/tasks/<workspace-hash>/tasks-<sessionId>.json

Global defaults live in ~/.pi/agent/tasks-config.json; explicit project overrides live in <cwd>/.pi/tasks-config.json. Normal task use does not create repository files.

Supported settings:

• taskScope: memory, session, or project
• autoClearCompleted: never, on_list_complete, or on_task_complete
• showAll, maxVisible, sortOrder, and hiddenAt

State event

Every mutation and session restore emits:

pi.events.emit("pi-tasks:state", {
  version: 1,
  reason: string,
  source: "tool" | "ui" | "session",
  tasks: Task[],
  activeTaskId?: string,
  at: number,
});

Consumers should treat this as coordination state, never as user authorization.

Upstream synchronization

Review upstream releases semantically. Preserve upstream task storage, dependency, reminder, and widget improvements when compatible. Do not reintroduce process execution, subagent RPC, or auto-cascade without an explicit architecture decision.