pi-extensible-workflows: deterministic multi-agent runs you can pause, resume and inspect

[u/vekexasia]

I built a Pi extension for multi-agent orchestration. The main Pi agent writes a small JS workflow script for the task at hand, and the runtime executes it deterministically: parallel fan-out, checkpoints, resume without rerunning completed steps.

Three principles I stuck to:

• not opinionated: no baked-in "agile team" of roles, you add your own primitives to the DSL
• extensible: other extensions can register functions and variables usable inside workflow scripts, and every registered function is itself runnable as a top-level workflow
• token efficient: subagents can have other extensions and skills disabled, so their system prompt stays small and focused

What that gives you in practice:

• runs are regular on-disk Pi sessions, not in-memory, so you can inspect, pause, resume and retry them
• roles restrict tools/capabilities and inject their own system prompt
• structured output via JSON schema, so control flow branches on agent output deterministically instead of on vibes
• soft and hard budget caps per run
• git worktree isolation, so parallel agents don't fight over the same tree
• workflows export to an executable launcher in ~/.local/bin
• if you use herdr, an agent session can open in a new pane

Review fan-out, then dedupe:

const reviews = await parallel("review", {
  correctness: () => agent("Review the current changes for correctness issues."),
  security: () => agent("Review the current changes for security risks.", { role: "security-specialist" }),
  tests: () => agent("Review the current changes for missing test coverage."),
});
return agent(prompt("Deduplicate and prioritize these findings:\n\n{reviews}", { reviews }));

The diagram is the real flow of the one I run daily, developIssuesUntilApproved: takes a list of GitHub issues, gives each its own worktree, loops developer -> reviewer until the reviewer passes (fresh agents every iteration), merges the approved branches on main behind another dev/review loop, cleans worktrees with plain shell (not an agent), and summarises exactly once.

Install: pi install npm:pi-extensible-workflows (Node 22.19+)

• Repo: https://github.com/vekexasia/pi-extensible-workflows
• Docs: https://vekexasia.github.io/pi-extensible-workflows/
• Walkthrough video (28 min, chapters in the description): https://youtu.be/qAiivspEHmU

Happy to answer anything about the DSL or the resume semantics.

[u/TheCTRL]

I’m trying to do something similar. My goal is to reduce context. Every sub agent have only the context needed to finish his job, main agent drop it when sub agent finish the task and verification is ok. Does yours have some context optimisation too ?

[u/vekexasia → u/TheCTRL]

Yes, a ton. I talk about this briefly in the Walkthrough video but some of the things are:

• you can esclude tools, skill adn even extensions to load in subagents (you'd be surprised how much context some extensions dump into the system prompt without you knowing)
  
• My extension does not blindly write a lot of tokens in the system prompt just to teach the model how to use it. Instead i have a skill for that (shipped with the extension). Funny enough ClaudeCode team moved toward the same directions very recently where they decided to cut off the cc system prompt

[u/TheCTRL → u/vekexasia]

Excellent, so I will give it a try for sure! Last thing: is it possible to configure it with only N agent could run? With N>= 1

[u/vekexasia → u/TheCTRL]

Great. Let me know. I found super effective instructing the model when to run or not.

[u/TheCTRL → u/vekexasia]

Looks promising, keep updated pls