pi-extensible-workflows

There are many workflow extensions but this one is Yours.

Turn multi-agent tasks into deterministic jobs that fan out in parallel, pause for approval, and resume without rerunning completed work.

Documentation | Developer guide | Roles | Extension authoring | LLM guide | Video overview

Requires Node.js 22.19 or newer. This is a trusted Pi extension with the same filesystem and process access as Pi.

Install

pi install npm:pi-extensible-workflows

For source installs and local development, see the installation guide. The repository is an npm-workspaces monorepo. The public package is maintained in packages/core; the private root keeps the existing npm run build, npm run lint, npm test, and npm run check commands working from the repository root. See releasing for the fixed-version policy.

Capabilities

The default path is a named inline workflow: write a script that fans out independent work with parallel(...), awaits the keyed results, passes them into one summarizing agent(...), and returns. Provide exactly one of script or scriptPath and a non-empty name; a reviewed JavaScript file's contents are captured in the run at launch. Registered functions are available as globals inside scripts, and args remains available to pass JSON values into the script. Runs are backgrounded by default; set foreground: true when the final value must be returned in the same tool call. Use /workflow to open the workflow picker, then choose a run and its contextual dashboard actions, including moving an attached foreground workflow to the background. The terminal result is then delivered as exactly one follow-up message. If a foreground tool call detaches before its result is accepted by the next event-loop turn, the terminal success or failure is promoted to exactly one follow-up message.

const reviews = await parallel("review", {
  correctness: () => agent("Review the current changes for correctness issues."),
  security: () => agent("Review the current changes for security risks."),
  tests: () => agent("Review the current changes for missing test coverage."),
});

return await agent(
  prompt("Summarize and prioritize these findings:\n\n{reviews}", { reviews }),
);

Advanced capabilities: Use registered functions, outputSchema, budgets, checkpoints, worktrees, retry/resume, CLI export, and pipeline(...) when the task requires them. They remain available without complicating the basic inline path. Workflow worktree scopes always use the explicit withWorktree(name, callback) form.

The main Pi agent writes these scripts on the fly for each task; an external review or approval flow can write one to a JavaScript file and launch it with scriptPath. Extensions can add reusable functions, and completed workflows can resume without rerunning completed work.

Direct consumers of createLocalPiSession() receive a session with extensions already bound. Await session.dispose() so session_shutdown runs before the native session is released; disposal is idempotent.

Learn more about roles, workflow contracts, and extension APIs in the documentation:

• Workflow tool and invocation API
• Global and project settings
• Aggregate run budgets
• Workflow DSL and worktrees
• Role files and per-call customization
• Extension authoring guide
• Copy-paste extension template
• Run artifacts and lifecycle events
• Run inspection and recovery
• LLM guide for installation, configuration, roles, extension authoring, and TypeBox function inference

License

MIT