todu-pi-extensions

todu-pi-extensions is a pi package that adds todu-focused commands, tools, and TUI workflows to pi. It is the pi-side integration layer for working with tasks from todu without leaving the agent.

Today the package is focused on task browsing, task detail, task creation, and task updates inside pi.

How it fits together

• pi is the host coding agent and extension runtime.
• todu is the task backend and CLI.
• todu-pi-extensions connects pi to todu.
• todu-workflow is an optional companion project with higher-level workflow skills and policies.

todu-workflow is not a hard dependency. You can use this package by itself, use it alongside todu-workflow, or build your own workflow on top of pi and todu.

Prerequisites

Install these first:

• pi via pi.dev, version 1.1.0 or newer within the 1.x release line
• todu via github.com/evcraddock/todu
• Node.js 22.19.0+
• npm
• overmind for the local dev environment

The tested Pi baseline is 1.1.0 for @earendil-works/pi-ai, @earendil-works/pi-coding-agent, and @earendil-works/pi-tui. Pi supplies these runtime packages and typebox; they remain wildcard peer dependencies, following Pi's package guidance, and are not bundled. Wildcard peer ranges do not imply support for older Pi versions. Node.js 20 and Pi versions before 1.1.0 are no longer supported.

Install the extension

Install the packaged npm release:

pi install npm:@todu/pi-extensions

Install project-local instead of globally:

pi install -l npm:@todu/pi-extensions

Install from git when testing an unpublished revision:

pi install git:github.com/evcraddock/todu-pi-extensions

Install from a local checkout while developing:

npm install
npm run build
pi install /path/to/todu-pi-extensions

Local path installs load dist/index.js, not src/index.ts. Rebuild after source changes so pi picks up the packaged output instead of live source files.

After installation, reload pi if it is already running.

Basic usage

Use the extension inside pi with commands such as:

• /tasks to browse and filter tasks
• /task to inspect the current task or a task by ID
• /task-new to create a task
• /task-clear to clear the current task context
• /todu-status to show Todu daemon and sync server status

The package also exposes agent tools for structured task operations such as listing tasks, showing task details, and creating or updating tasks.

For status-only task_update calls, omit assignee parameters or use null. assigneeActorIds: [] explicitly clears all assignees; empty add/remove lists are no-ops. See task update assignee parameters for details.

Task list/detail data preserves backend due, scheduled, creation, and update dates. Populated due dates also appear in tool text. See task date meanings and missing-value behavior.

task_list and task_show expose schema-validated structured envelopes to codemode while retaining readable text and compatible UI details. Check ok after every call, including fulfilled promises. See task read outputs and script examples. Other tool families still return legacy text.

For contributors, structured tool result contracts define the shared schemas, metadata safeguards, and result/error conventions.

For local compatibility verification, npm run smoke:codemode exercises packaged task reads through the real Pi SDK/codemode runtime with isolated synthetic state. It requires no external model credentials and stays outside default CI. See opt-in codemode smoke coverage and limitations.

Work on this project

npm install
make dev

make dev starts the local dev environment, including the isolated todu daemon used by this repository.

Useful commands:

make check
make pre-pr
make dev-cli CMD="task list"
make help

Release

Tag a version that matches package.json and let GitHub Actions publish @todu/pi-extensions to npm and attach the package tarball to the GitHub release. The workflow expects NPM_TOKEN to be configured in the repository secrets.

The isolated dev daemon keeps its state under .dev/ so local development does not touch your normal todu data.

License

MIT