osolmaz/pi-workflows

What it solves

pi-workflows solves the problem of managing complex, multi-step AI agent tasks that require a mix of LLM reasoning, deterministic code execution, and human oversight. Instead of relying on a single long prompt or unpredictable agent loops, it allows developers to define structured, durable workflows that can be paused, resumed, and monitored.

How it works

It functions as an extension for the Pi coding agent, allowing users to define workflows as TypeScript graphs. These graphs consist of nodes (such as agent for LLM prompts, compute for TS functions, shell for commands, and checkpoint for human input) and edges that determine the execution path.

Key technical components include:

• Durable Execution: State is persisted in a local SQLite database, meaning workflows can survive restarts or be paused for human decisions.
• Integration: Workflows are triggered via /workflow commands within Pi conversations, maintaining the context of the current discussion.
• Visualization: A dedicated terminal viewer (piw) provides a live, boxed-graph representation of the workflow's progress and history.
• Resource Managers: A declarative system to keep long-running automation aligned with external state (e.g., monitoring a PR).

Who it’s for

This tool is designed for developers using the Pi coding agent who need to automate sophisticated software engineering pipelines—such as automated planning, implementation, and verification—while maintaining granular control over the process.

Highlights

• TypeScript Graph Definition: Define complex logic, loops, and branching using a type-safe TS API.
• Human-in-the-loop: Built-in support for protected human decisions and checkpoints.
• Live Monitoring: Interactive TUI viewer for replaying steps and inspecting traces.
• Pre-built Skills: Includes bundled workflows for autopanning, auto-implementation, and sanity checking.
• Herdr Integration: Deep integration with the Herdr environment for seamless pane management.