pi-langgraph-workflow

A generic workflow guard extension for Pi that implements LangGraph-like workflows for coding-agent sessions.

It lets teams define project-local workflow graphs in JSON and then constrain the agent to move through those graphs with explicit transitions, joins, dynamic fan-out branches, and configurable node runners.

What it adds

Commands:

• /workflow start <name> — start .pi/workflows/<name>.workflow.json
• /workflow status — show the current session's workflow state
• /workflow graph — show static and runtime graph edges
• /workflow goto <node> — manually set the current node
• /workflow reset — disable the workflow guard for the current session

Tools:

• workflow_transition — move to an allowed next node
• workflow_fanout — create runtime branch nodes, similar to LangGraph Send
• workflow_run_node — run the current node with the command configured in the workflow file

Install

Global:

pi install npm:pi-langgraph-workflow

Project-local:

pi install -l npm:pi-langgraph-workflow

Then restart Pi or run:

/reload

Workflow files

Put workflows in your project:

.pi/workflows/<name>.workflow.json

Start one:

/workflow start <name>

Runtime state is session-scoped and stored under:

.pi/workflows/.state.<sessionId>.json

Add this to your project .gitignore:

.pi/workflows/.state*.json

Minimal workflow

{
  "entry": "build",
  "finish": ["done"],
  "runner": {
    "type": "command",
    "command": ["npm", "run", "workflow", "--", "{template}", "--run-dir", "{runDir}"],
    "itemArgs": ["--item", "{item}"]
  },
  "nodes": {
    "build": {
      "description": "Build the project",
      "allowedTools": ["workflow_run_node", "workflow_transition"],
      "next": ["done"]
    },
    "done": {
      "description": "Workflow complete",
      "allowedTools": ["workflow_transition"],
      "next": []
    }
  }
}

Example workflow

This package includes a safe example at:

examples/simple.workflow.json

Copy it into your project:

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

Start it:

/workflow start simple

Run the first node with workflow_run_node:

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

Then transition:

{
  "target": "plan",
  "reason": "discovery completed"
}

At fanout_items, create dynamic branches:

{
  "group": "items",
  "template": "process_item",
  "items": ["alpha", "beta", "gamma"],
  "join": "join_items"
}

This creates runtime nodes:

process_item:alpha
process_item:beta
process_item:gamma

After all branch nodes complete, join_items becomes available.

The example runner writes a log to:

runs/simple-demo/workflow.log

Runner placeholders

workflow_run_node expands these placeholders in runner.command, runner.itemArgs, and runner.cwd:

• {node} — full current node, e.g. process_item:alpha
• {template} — template part before :, e.g. process_item
• {item} — dynamic item part after :, e.g. alpha
• {runDir} — runDir passed to workflow_run_node
• {cwd} — current project directory

Node-level runner overrides workflow-level runner.

Notes

This is a workflow guard, not a distributed executor. It enforces LangGraph-like control-flow semantics for a Pi session. Dynamic branches can be completed in any order, but Pi does not automatically spawn multiple workers for them.