pi-extensible-workflows

Deterministic multi-agent workflow orchestration for Pi. Build named jobs that fan out, pause for approval, use isolated worktrees, and recover without rerunning completed work.

The repository README is the canonical product overview, package map, and documentation index.

Install

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

pi install npm:pi-extensible-workflows

Quick start

A workflow is a named inline or file-backed JavaScript script. Pi normally writes the script for the current task.

const reports = await parallel("review", {
  api: () => agent("Review the API."),
  tests: () => agent("Review the tests."),
});

return agent(prompt("Summarize these reports:\n\n{reports}", { reports }));

Launch with a non-empty name and exactly one of script or scriptPath. Registered functions are available as globals, and JSON-compatible launch values are available through args. Runs are backgrounded by default; set foreground: true to wait for the final value.

Programmatic integration

The package exports the workflow registry, runtime, persistence, validation, settings, role, lifecycle, and local Pi session APIs used by trusted hosts and extensions.

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

References

• Canonical overview
• Developer guide
• Subagents
• Herdr
• Roles
• Extension authoring
• Bundled workflow skill

Development

From the repository root:

npm run build --workspace=packages/core
npm test --workspace=packages/core
npm run lint --workspace=packages/core

License

MIT