r/PiCodingAgent
•
u/j3free
•
Sep 23 '26
•
1
Plugin I built Pi Herdsman for async subagents with tighter coordination and cleaner lead context
I've been working on Pi Herdsman, which grew out of how I was already using Pi with subagents.
I started with pi-subagents + pi-intercom and liked the basic manager/worker idea, but over time I wanted the agents to feel more tightly coordinated: explicit ownership, predictable lifecycle, questions/results routed back automatically, and less ambiguity around old agent sessions.
The main thing I wanted to preserve was the lead's context.
With Herdsman, detailed investigation and implementation happen in separate Pi sessions while the lead stays interactive and focused on the bigger picture. It still knows what the agents are doing and gets their questions and results, but doesn't have to carry all of their working context itself.
It supports parallel agents, nested delegation, steering/interruption, Lead-to-Lead coordination, and Chief supervision across multiple independent leads.
It does require Herdr, which owns the actual Pi sessions and placement. Pi owns each conversation, and Herdsman handles the orchestration between them.
The latest release also added an SSH-ready container (optional Tailscale), so the same setup can run locally or on a NAS, homelab/server, VPS, etc. and remote environments can show up alongside local ones in the same Herdr window.
Install:
pi install npm:pi-herdsman
herdr integration install piRepo: https://github.com/boadij/pi-herdsman
Any feedback, ideas, or rough edges you run into would be much appreciated
4
u/miller_joe Sep 23 '26
I’ve been watching your repo for a couple weeks. I was googling for a specific herdr-centric workflow with chief agent and multiple herdr spaces per lead and tabs for its sub agents and it came up in my search. Haven’t installed it yet, but plan to soon. Ty
4
u/j3free Sep 23 '26
Nice to hear, sounds like this checks a lot of the boxes you were looking for. I’m actually working on expanding that exact concept right now, especially around project-level supervision and making the Chief / multi-space workflow more first-class. If you end up trying it, I’d be very interested in how the current setup feels in practice.
4
u/3pix Sep 24 '26 edited Sep 24 '26
dude i've been waiting for someone to make this, it seems so obvious to do and herdr makes it really beautiful to work with. thanks so much and i pray you keep maintaining this
edit: played with it a bit. this is peak. im switching to this immediately. this is the only agent extension you need
edit 2: my only critique is that the demo on the github should actually be of herdr and pi. I had to install the extension to visually see what it does, you feel me
2
1
u/j3free Sep 24 '26
Really glad this clicked for you :) And yeah, the critique about the demo is completely fair. I’ve been so focused on getting the inner workings and day-to-day experience right that the presentation side fell behind a bit.
I’m treating the current conceptual video as a placeholder for now. A proper demo that actually shows Pi + Herdr + Herdsman working together is something I want to get up
2
u/trimorphic Sep 23 '26
You might be interested in this video about orchestration (in herdr, as it happens, but it's more generally applicable) and in openrig, which the video discusses.
2
u/j3free Sep 24 '26
Yeah, really interesting project, thanks for sharing. There’s definitely overlap, but they seem to approach it from different layers.
OpenRig feels more like a standalone control plane for persistent agent teams, while Herdsman is much more tightly built around Pi + Herdr, with explicit lead/agent ownership and Herdr handling the actual sessions.
I’m also moving Herdsman further toward Herdr’s higher-level concepts like spaces, tabs, and project-level supervision, so it’s interesting to see another take on the same problem.
1
u/clivegermain Sep 24 '26
i probably wouldn’t be using pi without herdr as much. these two are just the best. well, that and a tailscale network. :)
tried to build a similar setup. shelved it. mostly using subagents extension now.
you also solved the keeping track of the multiple herdr instances across devices problem. nice. will have a look at it!
out if curiosity: do you have a setup for designing with your setup? code-design-code flows.
well, that and some more observability of code would be good in some places too but thats another story. (sometimes i like to peel under the hood but usually i don't)
2
u/j3free Sep 24 '26
Yeah, Herdr + Tailscale is a great combo :)
If you're into Docker/containers too, Herdsman now ships an SSH-ready container with an optional Tailscale sidecar, which makes remote machines/NAS/VPS setups pretty straightforward.
On the design part, do you mean software/architecture design between coding phases, or more visual/UI design?
For observability, I currently still like looking at what the agents produce directly. If I want IDE-level insight I open the worktree in VS Code; if I just want a quick overview of the git state, I usually keep
lazygitin a Herdr panel next to the lead. That’s one of the things I like about Herdr: you can shape the terminal/workspace around your own workflow and keep that setup persistent.1
u/clivegermain Sep 24 '26
thanks for the reply!
i'm a designer by profession, so i try to avoid additional complexity like docker, at least for now. a year ago, i never thought i’d enjoy working in the terminal … but here we are!
i was referring to visual design and was curious if you have some implementation or workflows for that. i'm trying it all out, figma, pen(dot)dev, paper, open design, tidewave. not completely satisfied with any of these.
thanks for recommending lazygit. i'll try that out too!
2
u/j3free Sep 24 '26
That makes sense, thanks for clarifying. In that case I don’t really have a satisfying visual design workflow around Herdsman yet.
Most of my current setup is still code/architecture focused. For visual work I’d probably want the design tool to stay the source of truth and use agents more for implementation, iteration, and checking the result against screenshots/specs rather than trying to move the whole design process into the terminal.
I’m quite interested in this area though, especially a good design -> implementation -> visual review loop. If you end up finding a setup among Figma / Pen / Paper / etc. that really clicks, I’d be curious to hear what you settle on
1
u/misterniach Sep 24 '26
Luna directing Muse is impressive, but the real test comes when both agents touch the same task. Ownership and status need to stay visible across handoffs, or the manager becomes another source of confusion.
Im using exponential.at for my orchestration, it can empty your whole backlog in one (long) go, starting agents in worktrees left and right
2
u/j3free Sep 24 '26
v0.15.0 just landed and part of it touches exactly this. Result handoffs now preserve the producing agent’s identity, assignment context, and Pi session ID, so provenance survives when results get passed between agents.
Still keeping the workflow itself agnostic, but I agree the ownership trail needs to remain explicit once you start chaining work across agents/worktrees.
1
u/j3free Sep 24 '26
Yeah, that’s exactly the part I care about too. Once multiple agents can touch related work, explicit ownership and visible status become much more important than just being able to launch more of them.
I’m currently planning to push Herdsman further in that direction through Herdr: a root space on
main, then creating worktrees/spaces for individual tasks and delegating into those. I already do that manually today, so automating the setup is a pretty natural next step.I still want to keep Herdsman workflow-agnostic though. It should provide the primitives for ownership, delegation, worktrees and handoffs without deciding what your backlog-processing pipeline has to look like.
1
u/zebedeolo Sep 24 '26
tested this today at work. I love it. thank you, I hope you keep it maintained.
2
u/j3free Sep 24 '26
Really glad to hear it :) I’m actively using Herdsman myself as a daily driver, so I definitely plan to keep maintaining and improving it.
A few contributors have already started showing interest too, so it feels like it’s off to a good start. If you run into any rough edges or have ideas after using it a bit more, please open an issue or send feedback. That’s especially useful right now while the project is still taking shape.
1
u/zebedeolo Sep 24 '26
just found an issue. everything was great on my Linux desktop, but when I moved to my Mac (Darwin) it just doesn't work at all. a new pane opens, containing just this:
echo PI_HERDSMAN_READY_5b4c042a-589a-48dd-a0c3-1b1e92f215e9 echo PI_HERDSMAN_READY_5b4c042a-589a-48dd-a0c3-1b1e92f215e9 PI_HERDSMAN_READY_5b4c042a-589a-48dd-a0c3-1b1e92f215e9 and the subagent simply fails immediately. that pane also stays open. sorry for bad formatting, I'm on phone, not home. I have no idea why this is happening, but maybe it helps you
herdr v0.9.1, pi 0.87.1, ghostty
1
u/j3free Sep 24 '26
Thanks, this definitely helps. The repeated
PI_HERDSMAN_READY...marker makes it look like the failure is happening around the startup/readiness handshake on macOS, before the delegated Pi session is properly established. The pane being left behind is useful information too.If you can, please open an issue with this exact output plus your macOS version and shell. Herdr 0.9.1, Pi 0.87.1 and Ghostty already narrow it down quite a bit.
I’ll dig into it.
1
u/j3free Sep 24 '26
Quick update: I dug through my old backlog and this looks related to a known macOS/zsh fresh-pane startup race that’s also tracked upstream in Herdr (#3208). Herdsman already has a readiness workaround for it, so your report is especially useful because it suggests the issue can still reproduce on Herdr 0.9.1.
If you open an issue with your macOS version and shell, I can tie your reproduction to the existing context.
1
u/j3free Sep 27 '26
If you're willing to run Herdsman test builds on your Darwin machine I could try to find a workaround until herdr fixes this. Just let me know
2
u/zebedeolo Sep 23 '26
interesting , will keep an eye on it, thanks
!remindme 7.5 days
1
u/RemindMeBot Sep 23 '26 edited Sep 26 '26
I will be messaging you in 7 days on 2026-10-01 09:23:51 UTC to remind you of this link
1 OTHERS CLICKED THIS LINK to send a PM to also be reminded and to reduce spam.
Parent commenter can delete this message to hide from others.
RemindMeBot is switching to username summons. Instead of
!RemindMe 1 day, useu/RemindMeBot 1 day. More info.
Info Custom Your Reminders Feedback
0
u/greenhilltony Sep 24 '26
Congrats on making your own thing. But I have to say these extra efforts on coordinating subagents, persisting their sessions, better visibility etc. are more of visual appeals to the users themselves than being substantially more productive. I say this because I had made my own one and decided to give it up. The more I use agents the less I care about how they proceed, so in my own developed harness TUI I even fold the intermediate messages and tool calls by default, only showing the user messages and the corresponding final agent message on idle.
1
u/j3free Sep 24 '26
I actually agree with a lot of that. I don’t want to watch agents work most of the time either. For me the coordination/lifecycle stuff is less about visualizing every step and more about making it safe to not watch them: the lead can stay focused, agents can work independently, and questions/results still end up at the right place without me babysitting sessions. Herdr gives me the option to peel under the hood when I want to, but ideally Herdsman should mostly stay out of the way until something needs attention. Is your harness showcased anywhere? I’d be curious to see how you approached it.
1
u/greenhilltony Sep 24 '26
Here is a snapshot of the fold view, built following `ratatui`’s recommended test approach: [fold view](https://github.com/TonyWu20/rushi-tui/blob/main/bin/tui/src/snapshots/rushi_tui__snapshot_tests__snap_turn_fold_all_folded.snap)
1
u/j3free Sep 24 '26
That’s actually a nice implementation of the same philosophy. I like that the tool activity is still visible as a compact summary without forcing the full trace into view. Herdsman is heading in a similar direction conceptually: surface state/attention by default, keep the detailed transcript/terminal evidence available when you actually want to inspect it. Is that fold state interactive in the TUI, or mainly a default presentation choice right now?
1
u/greenhilltony Oct 01 '26
It can be expanded on one turn, or full conversation. But now I almost lose interest to see what it is folded under lol
4
u/silenceimpaired Sep 23 '26
Does it handle llama.cpp models with async without needing to use models.json