pi-workflows

pi-workflows is an open-source workflow engine, JSON control-flow tool, and live terminal viewer built as an extension for the Pi coding agent. Created by Onur Solmaz and released under the MIT license, it lets developers define multi-step agent workflows as TypeScript graphs and trigger them at any point in a Pi conversation using the /workflow command. The project reached v0.17.3 as of September 2026 and has accumulated 284 stars on GitHub.

What It Is

pi-workflows extends the Pi coding agent with a durable, graph-based workflow runtime. Workflows are TypeScript files placed in .pi/workflows/ (project-level) or ~/.pi/agent/workflows/ (global), and each workflow is a directed graph of named nodes with a single entry point. The engine keeps all run state in a local SQLite database at ~/.pi/agent/workflows/state.sqlite, making runs durable across restarts. A package-owned server process manages execution, and closing Pi does not interrupt compute, action, or shell nodes mid-run.

Node Types and Authoring Model

The workflow graph supports several node types, each with a distinct role:

• agent — sends a prompt into the origin Pi conversation as a workflow step; waits for structured JSON output via the workflow tool, or for a normal assistant response when expectedOutput: assistantMessage() is set.
• compute — runs a pure TypeScript function with no side effects.
• notify — writes a durable message back to the Pi session that started the run.
• action / shell — performs side effects but must declare an idempotentEffect(...) or manualEffect(...) recovery contract first.
• checkpoint — parks the run in a waiting state until a human supplies input via /workflow answer.
• decision — asks the model to pick from a fixed set of choices; decisionEdge routes on the result with compile-time case checking.

Workflows support composition: a parent workflow can import a child workflow and connect its named exits without copying its nodes. Nested children share one run, trace, pause state, and cancellation state.

Bundled Skills and Examples

The npm package ships six optional skills that Pi discovers automatically:

• pi-workflows — teaches the agent how to operate and author workflows.
• monitor — starts and operates the built-in monitor workflow for polling external state on a schedule.
• autoplan — frames a problem, devises a production-ready solution, and writes a detailed implementation plan.
• autodoc — records an existing plan in canonical documentation.
• autoimplement — implements an existing plan, prepares a safe branch or worktree, runs verification, and handles PR comments and CI.
• sanity-check — reviews whether a contribution is necessary, focused, and well supported.

The examples/workflows/ directory includes complete runnable examples: echo, branch, shell, two-turn, plain-summary, autoplan, autoimplement, human-decision, approved-plan, and autoresearch (an iterative feature-search loop modeled after karpathy/autoresearch).

Terminal Viewers and Herdr Integration

Two viewers let developers watch runs live. The npm package includes a pi-workflows CLI snapshot viewer. A separate Rust crate named pi-workflows (installed via cargo install pi-workflows) provides the full piw interactive terminal UI with selectable themes, detailed trace and conversation inspection, temporal replay, and reconnecting remote viewing.

pi-workflows also ships as a Herdr plugin. After installing piw and pi-workflows, running pi-workflows herdr sync registers the plugin. Inside Herdr, a workflow widget shows a Ctrl+Shift+R piw shortcut that opens the server-owned run view in a split, tab, or new workspace.

Resource Managers

Beyond workflows, pi-workflows includes a resource manager subsystem for long-running automation. Resource managers store desired state in spec, report observed state through conditions and status, and reconcile a deduplicated resource key whenever an event or retry makes it ready. Files matching *.resource-manager.ts in .pi/resource-managers/ or ~/.pi/agent/resource-managers/ are discovered automatically. Resources are applied and inspected from Pi using /resource-manager apply, /resource-manager get, and /resource-manager reconcile.

Update: v0.17.3

The latest release is v0.17.3, published on September 14, 2026. The repository was created in July 2026 and has seen active development, with the last push matching the latest release date. The project notes that its workflow model was originally ported from the openclaw/acpx flows project, and the autoplan skill replaces the earlier autodevise name.