pi-workflows: Adding Workflow Orchestration Capabilities to AI Programming Assistant pi

pi-workflows is an extension for the TUI-based AI programming assistant pi, enabling developers to define multi-step AI agent pipelines using simple JavaScript/TypeScript scripts. It supports running, monitoring, and debugging these workflows via pi's TUI, addressing the limitation of single-round AI assistant interactions for complex tasks. Key features include phase-based structuring, traceability, structured output with JSON Schema, and a local web dashboard for visualization.

AI programming assistants have evolved from code completion to context-aware tools, but most still operate in single-round dialogue mode. This falls short for complex tasks requiring multi-step, dependent actions (e.g., analyzing code structure → modifying files → running tests). pi-workflows was created to solve this by enabling structured orchestration of AI agent execution.

pi-workflows is an extension for pi (a TUI AI assistant by earendil-works). Its core value is letting developers define complex workflows with JS/TS scripts and run them via pi's TUI. Design principles:

• Phases: Workflows split into logical stages (e.g., Discover, Analyze).
• Traceability: Every step's state, time, and output are recorded for debugging/audit.
• Structured Output: AI outputs can be validated with JSON Schema for reliable use in subsequent steps.
• Concurrency: Parallel processing within stages while maintaining order between stages.

pi-workflows provides a runtime API for workflow scripts:

1. agent(prompt, opts): Calls an AI agent with tools (file access, bash) and optional JSON Schema for structured output.
2. pipeline(items, ...stages): Processes items in parallel within stages, sequentially between stages.
3. step(name, phase, fn): Wraps non-AI local tasks for traceability.
4. log(message): Shows progress notifications.

Example workflow: Define meta (name, phases) and an execution function using the API. Workflows are discovered from local/global directories (e.g., .pi/workflows/). Commands like /workflow start test-plan run workflows; /dashboard launches a web UI for visualization.

Technical modules: index.ts (entry), loader.ts (workflow discovery), runtime.ts (API), store.ts (persistence), types.ts (TypeScript types). Uses Bun runtime with 39 unit tests.

Constraints/best practices:

• All declared phases must be used in code.
• Non-AI tasks must use step instead of raw code.
• Phase names in code must match meta exactly.
• Deconstruct runtime functions (agent, pipeline, etc.) in the workflow function signature.

Ideal scenarios: batch code refactoring, test generation, documentation creation, dependency analysis, code reviews.

Compared to LangChain/AutoGPT:

• TUI Integration: Seamless with pi's terminal workflow (no context switch).
• Simplicity: Uses standard JS/TS (no complex DSL).
• Traceability: Full step logging.
• Structured Output: Native JSON Schema support.

Current limitations: lack of workflow dependency/composition, limited visualization options, no template sharing, no CI/CD integration. Future directions: address these gaps.

Conclusion: pi-workflows evolves AI assistants from passive tools to active task partners, enabling structured, reproducible use of AI for complex dev tasks. For pi users, it's a valuable extension to enhance AI utility in software development. Project link: https://github.com/umutbasal/pi-workflows.