@wichayutdew/pi-workflows

A declarative, pauseable workflow harness for Pi

Packages

Package details

extension

Install @wichayutdew/pi-workflows from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@wichayutdew/pi-workflows
Package
@wichayutdew/pi-workflows
Version
3.3.0
Published
Aug 22, 2026
Downloads
2,337/mo · 242/wk
Author
wichayutdew
License
MIT
Types
extension
Size
891.4 KB
Dependencies
1 dependency · 3 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts",
    "./src/herdr-workflow-state.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

codecov

Pi Workflows

Make repeatable Pi agent work explicit, durable, and safe to continue.

Pi Workflows is a declarative, pauseable workflow harness for Pi. Define steps, tools, prompts, approvals, and outcomes in YAML; it provides bounded execution, durable checkpoints, main-session step policy, and a live status view without dictating your language, framework, or delivery process.

See it in action

At a glance

Summary and status Workflow details
See progress, approvals, and outcome at a glance. Inspect each workflow step and its execution details.

Why Pi Workflows

  • Turn multi-step agent work into clear, reviewable workflow definitions.
  • Pause for human approval and resume from the same durable checkpoint.
  • Keep worktree-bound iterations safe, including follow-up enhancements.
  • Enforce declared resources and stop unsafe loops before they run away.
  • Assign a workflow-owned role prompt with agent: planner, worker, reviewer, or scout; customize profiles under ~/.agents/agents.

Herdr workflow status

When Pi runs delegated workflow steps, the parent agent may be idle while child work continues. Pi Workflows includes a Herdr companion extension that reports workflow lifecycle state so the pane remains working until the workflow completes, pauses, or is interrupted.

The companion is inactive unless Herdr provides HERDR_ENV=1, HERDR_SOCKET_PATH, and HERDR_PANE_ID. It uses Herdr's existing managed Pi reporter, so it does not create a competing pane agent.

Install from npm

pi install npm:@wichayutdew/pi-workflows

Start a new Pi session in Herdr, then run a workflow normally. Herdr should show the pane as working while the workflow is active and display the terminal workflow message after completion or interruption.

Reapply after a Herdr update

Herdr manages ~/.pi/agent/extensions/herdr-agent-state.ts; an integration update can replace the workflow lifecycle patch. Locate the installed package with pi list, change into that package directory, and run:

npm run patch:herdr

The script patches the managed integration at its default location. It is idempotent, so it is safe to run after every Herdr update. To patch a non-default integration path, set HERDR_PI_EXTENSION_PATH before running the script:

HERDR_PI_EXTENSION_PATH=/path/to/herdr-agent-state.ts npm run patch:herdr

Restart Pi or run /reload after patching. If Herdr's managed extension changes shape and the script reports an unsupported layout, do not edit it manually; update Pi Workflows or report the integration change.

Explore

License

MIT