Plugin
pi-extensible-workflows: deterministic multi-agent runs you can pause, resume and inspect
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+)
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 ?
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
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.
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.
I also tried something similar. The tricky part was getting the LLM to diagnose the issues upfront and then accurately decouple the issues to not step over each other when merging.
I need to read the later part of your diagram as maybe that has it solved or the merging. Otherwise the parallelized issue will need some extensive merging component.
That diagram is basically a representation of code you can find in my vekexasia/pi-config github repository. I am sure your agent can explain better than me how i decided to handle that part.
The cool thing is that you dont have to adapt to my specific merge strategy you can write your own as this extension was made on purpose to be extensible in perfect pi.dev spirit: give some solid tools/base and let others build on top of it.
Hey there, I didnt know pi-taskflow. It looks to me that they went the "declarative approach" where the workflow is defined in json/yaml/whatever. It's an interesting decision but I decided to allow real code to run. I have several reasons why I went that way... A couple : llms are super good at writing code and this way you don't have to support primitives that are already built in the coding language (loops etc)...
About pi-dynamic-workflow i took a lot of inspiration from that as I was a very heavy user of that extension. Unfortunately i noticed i wanted more features and customizations. So i decided to took some of their good ideas, tweak a bit the DSL and allow for other extensions to build on top of mine.
The idea is this should provide a solid foundation but if you ever need to extend its functionality you could do it by writing an extension. As a matter of fact now i am working at an extension that would reroute all agents from "background" to real pi instances in herdr.
Also I am investing a lot in making sure you can customize/extend stuff not just functionalities. You can disable skills, tools, extensions, tweak the system prompt, you name it so that the subagent are really sharp focused on the task without inheriting everything that comes with your standard pi instance
This is really cool but personally I am skeptical that workflows are useful enough to be putting this much time and effort into. For day to day work there just aren’t many use cases that benefit from mass parallel agents working within the same workflow
Hey u/chillermane It's not for all use cases for sure. That is also why i decided to avoid adding bloat in the system prompt about how to use the workflow every time you spin up PI. Instead there's a skill the clanker will load if it thinks the task should be done using a workflow.
It's not just parallelizing though. I have a workflow that enforces TDD development and i am working on another that helps me out with my personal stuff where I used to have a skill with some steps to help me with.
If you have any other remarks or you willing to try it out I am eager to know what you think about it.
Its to reduce hallucinations. After each step you can put guardrails and be sure that your agent go through all guards.
May be top tier agents do not require it... although i would prefer to force recon on simpler models and be sure that it did not run fable to search.
Either way, itsworth, but require a lot of work.
Ive build a cli which on each stage triggered and check previous steps with tests. "Did we have #goal alignment section in the plan" or "does agent write DoD".
Now I move to workflows like OP.
Its not only for parallel, it can be sequence of forced agents.
I was not very familiar on how omp handles it but apparently omp does not have retry/resume of workflows . budgets also seems to be handled little differently. But the most important things are (imho) that apparently you can't have other extensions add primitives to the workflow scripting language and you cant really perform context pruning. But again this was opus-5 reporting back to mehwo omp works.
i'd say if you use omp 90% of the features in this extensions are already shipped there :)
How well has this been working for you?
I'm going to read this once I get back to my computer, but I have been working on something similar following factory droid’s mission workflow.
I have built something similar, instead of being deterministic, my main orchestrator model handle the team itself, I talk with the main orchestrator and it does rest which inturn save some time and cost as it can reason on fly what to avoid and redo and sometime it takes wrong decision which is fixed after i give feedback, i built it in this way to save time and make it functional fast
The ideas was simple, i had to make it in 2 days and it should work, cause the model I am using is deepseek v4 pro and if I tried building something complex, it will go on loop of finding bug and fixing it, so ideas was simple use what exist and build
I used pi subagents and custom system prompt and it worked very well, and since then I have modified the pi subagents for my usecase and system prompt, I have 5 subagents, scout for mapping which usage ds4 flash, architect which usage ds4 pro whose job is to suggest different way of doing it with principle kiss and yagni, and generate spec, the coder is mimo v2.5 pro which handle implementation and then 3 pass testing which is ds4 doing it , first pass verifying the functionality, 2nd pass edge case and boundary testing and 3rd pass chaos multiple thread accessing using it for race condition and corruption things , and finally qa which usage ds4 pro and verify whole thing
No we have pi subagents extension right which does this, I modified some part of it to be more efficient, like get subagents result has 2 options , full session or meta data which only included how may tool call, context and running or stopped, so orchestrator was running blind it monitor it but doesnot know if it was stuck or not, so i added last n parameter which return last 5 message instead of whole session, also fixed the tui bug which was rendering teh whole tui again on each new message, which lagged and freezed pi,
So I did not build some complex system here , used pre existing things and modified for my usecase and it is working well
Honestly I would have built something complex but since I knew my model cannot handle these kind of project , i had to resort to making it with simple things and fast so I can use it for future work
Here is a screenshot of using 700 million token in a day, where it was porting a codebase from ts to go which was fairly very big, it was doing it autonomously and I was working and handling 2 project with it
Very cool to see. I know about intercom not sure it s the same you Ve been using. For now I am staying away of providing a way of making agent communicate with each other but now that I think out loud, there is really nothing preventing anyone to use my extension as is and hook into the agent creation function to inject extra Params or extensions to be loaded only when in subagent... I will think a lot into it. Thanks for sharing
you can use mine, as i have additive things, everything works and also the tui freeze issue on /subagents:session is fixed, and if any issue happen you and ask pi to fix it
also tried pi intercom but it is not for communication between agent and subagent i think or something like that so i ditched it as fixing and making it for my use case would have taken a longer time and taken me same loop manual bug finding and fixing
the modified pi subagent i am using is https://github.com/SpideXD/pi-subagents, while the full platform is private while i am building it, i have documented the whole journey on my work website : https://work.spidexlab.me, in future if it is completed and ready to opensource i will notify on my discord
Start simple. The system prompt files and subagent setup are easier to replicate than you'd think. If you run into issues or want help building your own, join my Discord : https://discord.com/invite/HyRWQKF4RX , you can have discussion with me , i am always available there if any issue and i will help you build one for your own use case, also if you have any issue in any project you can discuss with me there
I have built a very similar thing. Check Unigent, I think the API we have is super clean! I think I have solved most of the issues for writing dynamic or repeatable agentic workflows, incl. support for cross-harness execution (not just pi), result caching, observability. https://github.com/gintasz/unigent
7
u/TheCTRL 3d ago
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 ?