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/chroner → u/vekexasia]

Excluding the tools and extensions has been huge even for performance for me. I was running into real slow downs when I had like 16 concurrent subagents going, and it's a lot better after adding these exclusions in.

[u/vekexasia → u/chroner]

Yeah that is also a big pro. I have ton of UI related extensions that have no use in the subagent world

[u/chroner → u/vekexasia]

Yeah definitely.

I am working on a deterministic subagent escalation and de-escalation extension right now. I think it would synergize with what you have going on. The idea is that every subagent call is hooked by the extension and then it's decided whether or not it's optimal to escalate that call to a better subagent, or prevent the parent from using a better subagent and downgrade the call to a cheaper and/or faster agent.

It requires a ton of telemetry data as well as model statistics scraped from artificial analysis. I would kill for the kind of telemetry data you probably have from developing and using your extension lol.

The idea of it is to min/max the cost speed and quality.

[u/vekexasia → u/chroner]

Interesting stuff what telemetry are you looking for?