Pi extension for coding-agent sessions

Put agent work on rails with project-local workflow graphs.

pi-langgraph-workflow lets teams define strict JSON workflows for Pi, then guides the agent through explicit transitions, dynamic fan-out branches, joins, and node-specific runners.

Install extension See example

A workflow graph with discover, plan, fan-out, branch, join, summarize, and done nodes

Strict transitions Move only across configured graph edges.

Runtime branches Create branch nodes from discovered items.

Command runners Run node logic through project-defined commands.

How it works

A workflow guard, not a distributed executor.

The extension reads workflow definitions from .pi/workflows, stores session-scoped state, and injects the active node into the agent prompt. Tool calls are checked against the current node before they run.

Define the graph

Create <name>.workflow.json with an entry node, finish nodes, allowed tools, and edges.

Start the guard

Run /workflow start <name>. The current node becomes part of the session state.

Move deliberately

Use workflow_transition, workflow_fanout, and workflow_run_node to progress.

Install

Add it globally or per project.

Global install

pi install npm:pi-langgraph-workflow

Project-local install

pi install -l npm:pi-langgraph-workflow

Reload Pi

/reload

Commands and tools

Small surface area, explicit control.

/workflow start <name>

Loads .pi/workflows/<name>.workflow.json and places the session at the entry node.

/workflow status

Shows the active workflow, current node, available runtime nodes, and completed nodes.

workflow_transition

Moves to an allowed next node and marks the previous node as completed.

workflow_fanout

Creates runtime nodes such as process_item:alpha and unlocks the join after all complete.

workflow_run_node

Runs the configured command for the current node with placeholder expansion.

/workflow graph

Displays the static graph plus any runtime fan-out edges created in the session.

Example

Start with the included workflow.

The repository includes examples/simple.workflow.json. Copy it into a project, start it, run the current node, then transition through planning, fan-out branches, join, summarize, and done.

State stays local. Add .pi/workflows/.state*.json to .gitignore so session state does not land in commits.

mkdir -p .pi/workflows
cp examples/simple.workflow.json .pi/workflows/simple.workflow.json

/workflow start simple

workflow_run_node({
  "node": "discover",
  "runDir": "runs/simple-demo"
})

workflow_transition({
  "target": "plan",
  "reason": "discovery completed"
})

Runner placeholders

Pass runtime context into your command.

{node} full node name {template} node template before : {item} dynamic branch item after : {runDir} run directory passed to the tool {cwd} current project directory