pi-tasks

pi-tasks

Persistent shared task lists for Pi agents and MCP clients.

When to use

• The user asks for task lists, todo queues, claims, assignments, handoffs, or status tracking.
• Work has multiple steps and should survive reload, compaction, or session changes.
• Multiple agents/sessions/MCP clients may coordinate on the same queue.
• You need to pick the next available unit of work instead of choosing manually.

When not to use

• A one-shot answer or tiny edit needs no durable task state.
• A normal prose plan is enough and the user did not ask for persistent tracking.
• A private list is inaccessible, unless the user explicitly confirms a bypass.

Minimal workflow

• Use task_help when unsure; its Pi UI output is concise and is the source of truth.
• Use task_lists action=find|get|create|delete to discover or manage lists.
• Use task_items action=create|add_many to populate a list.
• Use task_claims action=claim_next as the only normal way to move work to in_progress.
• A claim is a time-limited lock. claim_expires_at shows when it expires.
• Use task_claims action=refresh for long-running work so another agent cannot reclaim it.
• After expiry, the task still exists but the lock is stale; release_expired or a later claim_next clears that stale lock so the task can be claimed again.
• Use task_items action=update with notes for task-local working memory.
• Close tasks with task_items action=update and status done or canceled; outcome is required.
• Pause tasks with status blocked; omit assigned_to_agent_id to keep responsibility, pass null to release it.

Tool map

• task_lists: create, find, get, delete lists.
• task_items: create, add_many, update, reorder, delete tasks.
• task_claims: claim_next, refresh, release_expired claims.
• task_audit: read visible private-list bypass audit events.
• task_help: show workflow, schemas, and examples.

Common calls

Find lists for the current workspace:

{ "action": "find", "params": { "scope_type": "workspace", "scope_key": "/repo" } }

Create a shared list:

{ "action": "create", "params": { "name": "Release work", "scope_type": "workspace", "scope_key": "/repo" } }

Add several tasks:

{ "action": "add_many", "params": { "list_id": "release", "tasks": [{ "title": "Run tests" }] } }

Claim next task:

{ "action": "claim_next", "params": { "list_id": "release" } }

Complete a task:

{ "action": "update", "params": { "task_id": "task-id", "status": "done", "outcome": "Decision: ship. Actions: tests. Final state: green." } }