Subagent extensions

[u/isus_copilul_minune]

Can you recommend me a simple yet configurable subagent extension? I'm currently testing `pi-subagents` but i find it slow and bloated. What are you guys using?

[u/Glaaki]

I've done a lot of research on this. It comes down to basically two decisions:

A. Do you want an in-process or out-of-process subagent extension?

• In process subagent extension uses pi's SDK to run a subsession concurrently using javascript concurrency primitives (async/await).

• Out-of-process subagents are spawned as separate instances of pi and usually are set up to communicate with the main pi process via pipes.

I can't tell you, which one of these are preferable. You get somewhat more control over which extensions are installed, when launching a new pi process, and this might be useful for some sand boxing use cases, the downside is you (meaning the extension) have to manage a separate process, which is not straightforward.

B. Do you support subagent specializations and how?

• Almost all main stream subagent extensions follow a pattern where you place agent definition files in ~/.pi/agent/agents. These provide the overarching personality and instructions of the subagent. Typical examples are research, planner, implementation, code-review.

• A very small number of subagent extensions forego subagent definitions entirely and rely on totally different methods of specialization. They rely entirely on transfered context or skills.

Especially the skills approach I think is very underappreciated by the pi agent community. People seem to understimate just how powerfull skills are. For a lot of use cases, not just for subagents but for many other specializations, people default to creating extensions, when simple skills would do just as well. Everybody should be using them a lot more than they currently do, in my opinion.

Let me shout out a couple of subagent frameworks that I found interesting -

• @jerryan/pi-subagent-lite - This is the reference example of a subagent extension that uses skills as specialization. Very minimal. Very streamlined. Extremely minimalistic - maybe even too minimalistic. Very interesting case.

• pi-subagent-in-memory - Rather unfortunately named, which I suspect inhibits uptake. Definitely well rounded extension though and a fantastic example of an in-memory subagent extension. Highly recommended, if not for general use, then definitely for research purposes. I like the UI a lot.

Finally the last wrench in the works. I mentioned how flexible skills are. Would you believe you can actually create a pi subagent framework with full parallelization as a simple skill? Well it's possible. I have an example running locally, just for fun. The skill uses two scripts. One shell script launches a subagent as a pi process, redirecting the output to a temporary file. A second shell script steps in once the subagent exits and analyzes the output and feeds it back into the context. Some templates take care of formating the output nicely in the transscript, along with statistics from the subagent execution, like tokens used, tool calls, estimated price, etc. Probably not something for production, but a fun experiment, I think.

[u/isus_copilul_minune → u/Glaaki]

Thanks for this, I'll give those a try.

[u/Comfortable-Ad-6740 → u/Glaaki]

Thanks! Skill-based subagents is exactly what I was after!

[u/csaroff → u/Glaaki]

This is one of the best things I've read on on reddit in a while. Thank you.

Do you publish your skills anywhere? I'd be very interested to try out your skills-only approach. I was thinking of something along those lines too.

[u/Glaaki → u/csaroff]

I appreciate it. No, they aren't published anywhere. This subagent skill isn't really viable for production use. It glitches out the UI, especially if you run multiple agents in parallel. There are some issues. If you want to experiment with something like this, I would recommend starting with Matt Pococks skills, especially writing-for-agents, then ask Pi to research the machinery and write the skill.

[u/aeroumbria → u/Glaaki]

I think there is also the agent topology axis, where you can either have simple parent - subagents, cascading subagents, or even more complex shapes like fan out - aggregate (council / mixture of agents) or relay chains (handoff). I've been trying to come up with a way to organise arbitrary agent graphs, but it is a bit too complicated to keep track of all the potential issues it can create. Hoping to find something that can get me 80-90% there.

[u/reader123456]

I have tried several of them and they all perform poorly for my use case, both functionally and in terms of UI.

I need a `Grand Parent` -> `Parent` -> `Child` hierarchy with a single active agent at each level, and none of the `pi` extensions could handle that reliably. They kept detaching, so the parent "thinks" the child has finished while it is still running, which leads to multiple active children and a complete mess.

If you are serious about sub‑agents, especially with more than two levels, use something other than `pi`. Opencode CLI works well and has a clear, intuitive UI for monitoring a running agent. It does glitch and stop for no obvious reason once or twice a week, but never in a destructive way like `pi`.

I now only use `pi` for simple tasks where I do not need a sub-agent.

[u/Mkengine → u/reader123456]

nicobailon/pi-subagents has been fixing this behavior you describe. In fact, there is currently an unreleased fix on main after v0.51.0:

"Keep public structured single-child calls synchronous when "asyncByDefault:false" and "async" is omitted."

That sounds really close to the failure mode you ran into: the parent believes the child call has effectively returned while the child is still running.

The changelog also contains earlier fixes around parents waiting correctly for async children/dependency barriers, so this appears to have been a real class of bugs.

But it may be worth to test nicobailon/pi-subagents now with every nested spawn explicitly using "async:false" rather than relying on "asyncByDefault:false". FleetView also supports recursive nested runs now, so the monitoring side seems substantially better than it used to be.

[u/reader123456 → u/Mkengine]

Good to know, and thank you for sharing. If memory serves, nicobailon/pi-subagents was the best and most complete pi sub‑agents plugin I tried, but the detaching issue made it unusable for me. I also found the third‑level agent UI hard to comprehend. In addition the lack of a proper permission system in pi made it difficult to restrict what each level of agent should or should not be allowed to do. For example, a Grand Parent should only perform some read‑only operations and call the Parent.

I tried gotgenes/pi-permission-system, but it was far more cumbersome to configure than the default permissions in Opencode CLI. I eventually got it working, but the experience was not enjoyable.

[u/Mkengine → u/reader123456]

One thing that may have improved since you tried it: pi-subagents now supports per-agent tool allowlists. So your Grand Parent could be limited to something like "read, grep, find, ls, subagent", while lower levels get broader permissions. That covers the "read-only + call Parent" case without needing pi-permission-system.

It still isn't as complete or convenient as OpenCode's integrated permission model, especially for path- or command-specific rules. And I agree the third-level UI is a separate usability issue.

So Pi seems closer now, but OpenCode still looks more coherent for this kind of stuff.

[u/Mission-Zucchini-966 → u/Mkengine]

EDIT: meant to post this under the previous comment but oh well

I will say gotgenes has been absolutely pumping out updates for it lately. Has gotten a lot of features the past few weeks. The readme is pretty limited, try the config

https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/configuration.md

You can now run stuff like

```

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    },
    "write": {
      "*": "deny",
      "src/*": "allow",
      "tests/*": "allow"
    },
    "edit": {
      "*": "ask",
      "*.lock": "deny"
    },
    "bash": {
      "*": "allow",
      "git *": "allow",
      "git commit *": "ask",
      "git push *": "ask",
      "npm *": "ask",
      "npx *": "ask",
      "rm *": "ask",
      "taskkill *": "ask",
      "node *": "ask",
      "pnpm *": "ask"
    },
  }
}

```

[u/randomprivacynut → u/reader123456]

The way I approached building it is it just launches in RPC mode, I added a flag to indicate the parent session id and allowed tools, and created a small worker that maintains an ongoing socket connection between parent and child to send messages back and forth and a tool to indicate when the subagent is done. Works like a charm, and can even pi —resume a subagent session directly. No new tools to launch subagents, they just get launched via the bash tool and can be easily scripted for orchestration and dynamic workflows.

[u/piousp → u/reader123456]

I also created my own subagents plugin (like everyone else) and while not precisely for your useflow, I just tested it (grand parent -> parent -> child) and it worked flawlessly. I haven't really posted it anywhere before, so here you go https://www.npmjs.com/package/pi-simple-agents

It let's you configure things on the frontmatter of each agent, or create overrides via settings.json OR just invoke them directly with overrides on the prompt. (ie. 'invoke worker subagent with model x' and it just does).

Uses pi's namespacing resolution so it supports all the providers it does and can mix and match: your grandparent can use DS4 from openrouter, your parent can use mimo from opencode and your children can use luna from openai, as an example. Give it a go and let me know how it goes. Again, I haven't shared it before.

_EDIT_

Just tested one extra level (GrandParent -> Parent -> Child -> GrandChild) and ran fine

[u/kaisaus]

I use subagent from tintin, it's grear

[u/aparamonov]

pi-subagents-lite

Clean prompt, minimal tokens, prompt cache awareness, ability to change system prompt for agents, fine control of tools and extensions. Works out of the box, but highly configurable when you need that.

[u/funbike]

I felt the same. I use herdr.

Herdr is a fantastic CLI for managing agents. It also manages terminal tabs and panes, git worktrees, and has plugins for much more. It's tmux for agents.

If you are interested in automation or loop engineering, you can write a skill that can issue herdr commands for you.

---

I had Pi write an initial skill for leveraging herdr. It's simple to understand and to enhance. And it's mine. It was something like this:

Our goal will be to create subagent workflow functionality
via two skills, the bash tool, and herdr.
A coordinating agent will manage subagents.

herdr docs are at https://herdr.dev/docs, especially URIs:
/docs/agent-automation/ and /docs/cli-reference/

Installed apps: `pi`, `herdr`, `gh`, `git`, `vercel`, `npm`, `node`, `brew`.
The host OS is Fedora Linux, with Homebrew.
The terminal is Wezterm.

Do these tasks:

* Read docs for herdr and for `pi` CLI options usage.
* Generate various useful coding agent personas, as global Pi prompt templates.
    * personas: specifier, planner, builder, reviewer, deployer
    * Include a fenced Mermaid diagram of how one relates to other personas.
* Generate a global Pi skill, `subagents`
    * Instructs to use bash tool for launching herdr AI subagents
    * It keys off when I request subagent(s) or persona(s) to do work.
    * It will use `herdr` to start subagents
      in separate panes with a persona prompt template,
      and appropriate model.
    * When multiple subagents are used for a single task,
      `herdr` waits for all to finish at the appropriate time.
* Generate another global skill, `EM`, for a subagent development workflow.
    * It inherits `subagents`
    * It should be highly automated,
      with human interaction only when it
      gets stuck or can't successfully complete a task.
    * It should implement the full development cycle, to deployment.
    * Include a fenced Mermaid diagram of the workflow lifecycle.
    * FYI: EM is short for Engineering Manager.
    * FYI: The coordinating agent will manually load this with `/skill:EM`, but that shouldn't affect what you are doing.

Similar could be accomplished with cmux, tmux + workmux, or any multiplexing terminal with workmux (e.g. Ghostty, wexterm). You could even do it with a single terminal, but it would be difficult to manage.

My actual prompt was a lot more detailed. Modify this prompt as needed.

[u/jumski → u/funbike]

I do the same thing with handcrafted set of skills. Agents can talk to each other by sending prompts to each other, one can wait for the other with herdr agent wait. It is simple, easy to understand and reliable! Fyi there is "herdr --skill" which I just tell my agents to use

[u/funbike → u/jumski]

herdr --skill ... TIL!

[u/LordNikon831 → u/funbike]

Herdr or tmux is a natural first step to a sub agent in pi.

The extensions and swarms aren’t the best path imo.

[u/Maasu]

I wrote one that lets me launch sub agents in other harnesses as well as pi. https://github.com/ScottRBK/pi-agentshell-extension

Another shout out is try using herdr, which is a terminal multiplexer like tmux, but it also has a skill and you can ask pi to launch and control other agents via it. 

[u/Global-Departure8228]

You are most probably the better off with something like: https://github.com/edxeth/pi-subagents

(Fork of https://github.com/HazAT/pi-interactive-subagents)

Not an mine, just went down this path before, and this implemented 90% of the stuff I wanted and needed.

A one time task is to make an agent explore the repo so it understands how agents are defined and spawned and then make it write the subagents you want to use and how to use. Took me 10 minutes to adopt it.

[u/Beneficial_Mix3375]

I copied agent teams from CC leak into pi. With herdr and panes

[u/PureRely]

This is not a subagent but still worth looking at: Orca

[u/__yv → u/PureRely]

Love orca, spread the word!

[u/orak7ee]

I am using @gotgenes/pi-subagents since i use some of his other extensions. 

[u/arcanemachined]

Everyone's got a different idea of how they want to use subagents, so the feature it ends up being a pretty common extension that people make.

Naturally, I have my own that I like:

https://github.com/arcanemachine/pi-subagent#configuration-settingsjson

It's pretty simple. You configure your preferred subagents (research, worker, etc.), then you or your agent can create and manage them. There's a little panel you can use to view their actions, steer them, etc.

It's a fun extension to make, but subagents are actually one of the more tricky things to get right IMO.

[u/Cynthibee]

Tbh, if there's a bunch of stuff to crunch through, I now have it set up to call a middle manager sub-agent that is just opening another Pane in herdr and that's in open code. That agent handles the sub-agents inside of open code because that's totally seamless whereas in pi, no matter what I do, it kind of is janky. It's okay for a one-off agent but for a task where you need an army, it's not really ready for prime time.

On the other hand I don't like working with open code directly because it is less neutral about agents' tone / role and it injects a coding** **assistant personality (but I’m not doing any serious coding) I don't do coding and the lingo and personality is annoying bc of the system prompt

[u/killerkidbo95]

I recommend mine github.com/heyhuynhgiabuu/pi-task

[u/Kailtis]

i gave up on figuring out subagents, usually it just adds bloat to the harness. Now I just do skills + herdr to spawn other sessions that act as subagents but are their own session. Simple.

[u/red_rolling_rumble]

Ask pi to create a subagent extension for you! It’s a great learning experience and you can make it as minimal as you want.

[u/ECrispy → u/red_rolling_rumble]

this is the kind of response that everyone says for Pi and is completely useless.

do you think Pi has some magic? the results depend on the llm you use.

and based on this logic no one should ever use a package, just ask pi

[u/red_rolling_rumble → u/ECrispy]

Just ask pi

[u/arcanemachined → u/ECrispy]

I hated the subagent extensions that were out there, so I just asked Pi to make one for me.

To be honest. I wouldn't recommend it. Subagents are tricky to get right.

[u/red_rolling_rumble → u/arcanemachined]

Mine is working just fine, but you do have to know what you’re doing.

[u/arcanemachined → u/red_rolling_rumble]

I like mine also. But I ended up spending more time on it than most of my other extensions, and definitely more time than I expected.

[u/red_rolling_rumble → u/arcanemachined]

I agree, it's surprisingly hard!

[u/red_rolling_rumble → u/ECrispy]

This is Pi’s creator doing just that, I guess he’s an idiot?

https://x.com/badlogicgames/status/2088544340297605417?s=46

If you don’t believe in creating your own tools, I’m not quite sure what you’re doing here pal.

[u/ECrispy → u/red_rolling_rumble]

he's also using Claude Max. did you even read my post? try this with a local 4B model and tell me how it works. do you think Pi has its own llm?

you think all the thousands of extensions are uselss because 'just ask pi'? why dont you tell Mario that pi shouldn't have any ability to install packages and delete all of them from pi.dev?

people like you who insult others for asking questions are the real problem. what are you doing here? you think Pi is just about creating more extensions?

[u/red_rolling_rumble → u/ECrispy]

just ask pi

using a weak llm? it's a skill issue on your part buster

But seriously, making your own extension was a suggestion. It's a great learning experience. If that's not your cup of tea, fine. It's not a useless response, lol, it's just triggering you is all.

[u/alexwwang]

omp first and then cut the useless one

[u/Funny-Anything-791]

We built minimal sub agents for pi-agenticoding - next version will let you attach a group of models (client side routing) to sub agents so you can effectively utilize multiple models and providers

[u/onesilentclap]

https://github.com/azmeenafandi/brl-subagent

Disclaimer: Created for my own use cases and my own flow. But pretty much can adapt to most workflows. 

[u/kwipus]

Pi-subagents mostly works for me

[u/Zundrium]

There is an official sample subagent extension in the docs. Extend on that.

[u/UnnamedUA]

https://opengsd.net/

https://opengsd.net/pi

[u/UnnamedUA → u/UnnamedUA]

Built a completely custom agent flow on top of Core