@pify/task

Task tracking inside pi sessions — a dependency-aware list with a live widget, transient reminders, and completion that demands evidence.

Part of the Pify suite. Install with pify install task or pi install npm:@pify/task.

Why

A checklist an agent can tick without proving anything is a checklist that measures confidence rather than progress. This one asks for evidence at the moment of completion, knows which items block which, and speaks up when the list and the work drift apart.

Tools

task_create

Parameter	Type	Notes
subject	string	Short imperative title
description	string, optional	Detail the subject cannot carry
blockedBy	number[], optional	Ids that must complete first

task_update

Parameter	Type	Notes
id	number	The task to change
status	pending | in_progress | completed | cancelled, optional	Blocked tasks refuse in_progress and completed
subject / description	string, optional	Rewrite either
blockedBy	number[], optional	Replaces the full blocker set — include existing ids to keep them; the result echoes the resulting blockers
evidence	string, optional	Required to reach completed

task_list

No parameters. Returns the whole list plus the ready set — tasks with no open blockers, safe to start or hand to a parallel runner.

Behaviour

• A dependency graph, maintained for you. blockedBy and blocks are kept in sync in both directions. Self-dependencies, ids that do not exist, and cycles are dropped with a warning rather than accepted and left to deadlock later.
• Evidence-gated completion. Marking a task done requires stating what was actually checked — command output, test results, file state. "I wrote the code" does not pass. This is the same bar goal_complete holds elsewhere in the suite. Reopening a completed task clears its evidence, so re-completing it demands fresh evidence in that same update — an item cannot re-close on a previous attempt's now-stale proof.
• Unblocked work is reported where it lands. Completing a task answers with what it just made ready — Now ready (no open blockers, safe to parallelize): #2 write tests, #5 update docs — instead of leaving the agent to discover it through a separate task_list call it may never make.
• Reminders when the list goes stale. If open tasks are untouched for a few turns, or an in_progress task survives a turn that produced only text, a <system-reminder> listing the open items and their blockers is added to the outgoing request — at most once per turn, not on every call inside a tool loop, and never on a turn pi aborted or is about to retry.
• A sweep when the list finishes. The moment every task is marked completed is the moment a list is most likely to be lying: each item passed its own evidence check, which proves the plan was followed, not that the plan covered the request. A completing list therefore earns exactly one reminder to re-read what was asked, look at the real output rather than the memory of producing it, and add a task instead of reporting done if something was quietly narrowed. It fires once per completed list, and reopening the list arms it again.
• Both injections are transient. They are added to the outgoing request through the context hook and never written to the session, so they cannot accumulate and cannot break an earlier prompt-cache prefix.
• Live widget. ☑ tasks 2/5, with ✳ in progress, ◻ pending, ⊘ blocked by #2, ✔ done.
• Session-persistent. The list survives /reload, resume, and branch switches through snapshot entries with last-wins replay. Snapshots written by an older schema are repaired on replay rather than trusted.

Command

/tasks — print the current list, statuses, blockers, and ready set.

task vs todo

	@pify/task	@pify/todo
Audience	User-facing tracking	The agent's own scratchpad
Structure	Dependency graph	Flat list
Completion	Evidence required	Just mark it
Reminders	Stale-list nudge and completion sweep	None — it stays quiet

They coexist: verifiable project tracking here, quick working memory there.

Where this sits in the suite

@pify/task tracks work; it never executes it. Delegation is @pify/subagent, parallel fan-out is @pify/swarm, and scripted pipelines are @pify/workflow — the ready set is designed to be handed straight to either of the last two.

License

MIT © Pify maintainers