@crooycom/pi-workflows
Generic workflow engine for coding agents — runs a JS workflow script that fans work out to subagents through an injected agent runner. Stripped fork of @quintinshaw/pi-dynamic-workflows 3.14.0: roles, model tiers, commands, TUI and builtin workflows remo
Package details
Install @crooycom/pi-workflows from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@crooycom/pi-workflows- Package
@crooycom/pi-workflows- Version
0.3.0- Published
- Nov 20, 2026
- Downloads
- 428/mo · 428/wk
- Author
- crooycom
- License
- MIT
- Types
- package
- Size
- 1.3 MB
- Dependencies
- 3 dependencies · 3 peers
Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-workflow-script
Site: site/index.html · Explainer: site/explainer.html · Repo: https://tangled.org/crooy.tngl.sh/pi-workflows
A generic workflow engine for coding agents — forked and stripped from
@quintinshaw/pi-dynamic-workflows 3.14.0 (MIT). It executes a JavaScript
workflow script that delegates work to subagents via an injected agent runner,
and almost nothing else: no opinions about what work to run. Who runs the
work is pluggable — the shipped default runner speaks pi, and a host can inject
its own.
Roles, builtin workflows, model tiers, commands, TUI and authoring tooling
were all removed in the strip (29 of 55 modules) — supply them as data.
Provenance and strip history: see FORK.md. This repo is the only known home of the 3.14.0 sources.
The script contract
A workflow is a plain JavaScript file. It starts with import "pi-workflows/register",
and ends by handing its result to finish():
import "pi-workflows/register"
const meta = { name: "my_flow", description: "what this does" } // optional
const draft = await agent("write a draft about X")
const review = await agent("review this: " + draft, { model: "provider/model" })
const both = await parallel([
() => agent("check A with " + review),
() => agent("check B with " + review),
])
finish({ draft, review, both })
Run it with node my_flow.js. The import
launches the engine: it validates the file, journals the run, prints
meta/result/token usage, and exits 0 or 1. Resume a stopped run with
node my_flow.js --resume <id>. Scripts embedded via WorkflowManager
(in-session, tests) keep the classic shape: first statement
export const meta = …, result as a top-level return.
Script globals injected by the engine: agent, parallel, pipeline,
workflow, verify, judgePanel, judgedLoop, completenessCheck, retry, gate,
checkpoint, log, phase, pick, finish, args, cwd, process, budget,
console.
Execution runs in a node:vm realm with a determinism prelude — host
built-ins (Date.now(), Math.random(), imports, fs) are deliberately
unavailable. The value handed to finish(result) becomes the run result — a
top-level return still works for engine-embedded scripts.
agent() options (data, per call): model, thinking, label, phase,
schema (structured output), tools/disallowedToolNames allow/deny, skills
(forced skill load),
isolation (git worktree), cwd, thread, timeoutMs, retries.
Quickstart
- Save a small workflow file, for example
hello.js, in your project:
import "pi-workflows/register"
const meta = { name: "hello", description: "smallest possible run" }
const answer = await agent("Reply with one fun fact about the number 42.")
finish({ answer })
- Run it:
node hello.js. The engine journals the agent call, prints the result, and exits 0. - In a pi session, load the exported tools yourself:
createWorkflowToolandcreateWorkflowControlToolfrom the package root. The package registers nothing on load.
CLI
The package ships a pi-workflows bin:
pi-workflows run hello.js # the include line is optional here
pi-workflows runs # list this project's runs
pi-workflows show <id> # inspect one run (--json for the raw record)
pi-workflows resume <id> # continue a journaled run; no file needed
pi-workflows inbox [--all] # open questions from parked runs (--all: every project)
pi-workflows answer <qid> --option 1 # answer a parked question (interactive on a TTY)
pi-workflows clean --older-than 7d --yes # delete terminal runs
pi-workflows skill # print the authoring guide for agents
run accepts scripts with or without the import "pi-workflows/register"
line; node hello.js with the include keeps working unchanged. runs, show,
inbox, and clean scope to the current project (the cwd the run started in).
A script can pause for input with askUser({ prompt, options }): the run parks,
the question lands in the inbox, and answer + resume continue it —
headless-friendly, see docs/adr/0003-ask-user-questions.md. After
global install use npx @crooycom/pi-workflows. Decision record:
docs/adr/0002-cli-returns.md.
Install
npm install @crooycom/pi-workflows
The package is a library. It ships no pi extension and adds no tools on load.
import { WorkflowManager } from "./src/index.ts";
const manager = new WorkflowManager({
cwd: "/path/to/project",
agent: myAgentRunner, // (prompt, options) => Promise<unknown> — YOU provide this
});
const result = await manager.runSync(script, args);
// result.meta, result.result, result.agentCount, result.tokenUsage, ...
WorkflowManagerOptions.agent is the integration seam: the engine never
calls a model itself — the embedding host supplies the runner. Persistence
(run-persistence + run-record-store) journals each call under
~/.pi/workflow-script/projects/<cwd-hash>/runs/ so runs can resume from their
journal (resumeFromRunId). For a durable spine (crash-safe tasks, resumable
conversations) see the sibling pi-factory framework. It wraps this engine in
pi-durable, but the
engine itself does not depend on it — its only runtime dependency is acorn.
Development
npm install
npm run check # tsc --noEmit, strict — must stay at 0 errors
npm run smoke # end-to-end run with a fake agent runner (no model calls)
npm test # both
Note: this repo ships compiled dist/ for installs. npm install and every
git install run prepare, which builds dist/ from src/ with
npm run build. Run tests against src/ via tsx; installed copies run plain
node against dist/.
The runner seam
The engine never calls a model itself. The host injects one runner. One call
runs one agent job: (prompt, options) => Promise<unknown>.
import { WorkflowManager } from "./src/index.ts";
const manager = new WorkflowManager({
cwd: process.cwd(),
agent: { run: async (prompt) => myRunner(prompt) },
});
const result = await manager.runSync(script, args);
pi-workflows ships one runner. It spawns one pi --print --no-session child per job.
Any other host swaps its own runner in here.
Child sessions load no host extensions unless explicitly opted in: the
childExtensions option names individual extensions, each of which loads by
explicit path; skills resolve from the workspace only. The old option name
providerMiddlewareExtensions still works this release as a deprecated alias.
What was stripped
Builtin workflows (code-review, deep-research, adversarial-review),
agent-type registry/roles, model tiers, all slash commands, saved-workflow
storage, usage-limit scheduler, web tools, TUI (task panel, navigator,
progress widgets), authoring/ comprehension/ release-gate tooling, and the
capability-contract's authoring diagnostics (its runtime-binding table lives
on inside workflow.ts). Removed features fail loudly: agentType throws
SCRIPT_VALIDATION_ERROR.
License
MIT — © QuintinShaw / Michael Livs, see LICENSE.