# pi-workflows

> A workflow extension for the Pi coding agent that lets you define multi-step agent workflows as TypeScript graphs and trigger them in Pi conversations.

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.

## Features
- Define multi-step agent workflows as TypeScript graphs
- Trigger workflows in Pi conversations with /workflow command
- Durable run state persisted in local SQLite database
- Agent, compute, notify, action, shell, checkpoint, and decision node types
- Workflow composition with nested child workflows
- Bundled skills: autoplan, autoimplement, autodoc, monitor, sanity-check
- Interactive terminal viewer (piw) with temporal replay and themes
- Resource manager subsystem for long-running automation
- Human decision checkpoints with protected approval gates
- Always-on server that survives Pi session close
- Herdr plugin integration with pane placement shortcuts
- Workflow pause, resume, and cancel controls
- Telegram channel integration for human decision notifications
- Monitor workflow for scheduled polling with optional repair policy
- Workflow composition with controlLoop() for bounded branches

## Integrations
Pi coding agent, Herdr, Telegram, npm, cargo/crates.io, SQLite, TypeScript

## Platforms
CLI, API, DEVELOPER_SDK

## Pricing
Open Source

## Version
v0.17.3

## Links
- Website: https://github.com/osolmaz/pi-workflows
- Documentation: https://github.com/osolmaz/pi-workflows/blob/main/docs/WORKFLOWS.md
- Repository: https://github.com/osolmaz/pi-workflows
- EveryDev.ai: https://www.everydev.ai/tools/pi-workflows