Pi Herdsman plugin
Pi extension for background subagents: parallel delegation, a Manager, Lead and Agent chain and supervision in herdr
- 226 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- Runs background agents that change files and Git branches in parallel without constant human attention
- Nested delegation lets agents assign work to other agents, so activity is hard to take in at a glance
- Messages between machines travel over SSH, and the installer runs through curl and sh
Install
Manual install
curl -fsSL https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.sh | shScript for Linux and macOS, with install.ps1 for Windows. Read the script before running it.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Runs background agents that change files and Git branches in parallel without constant human attention
- Nested delegation lets agents assign work to other agents, so activity is hard to take in at a glance
- Messages between machines travel over SSH, and the installer runs through curl and sh
This is third-party code. Review the repository files before installing.
What it does
Pi Herdsman connects the Pi agent with the herdr terminal multiplexer. Pi runs the conversation, herdr holds terminal sessions and workspaces, and Herdsman handles delegation and supervision. An ordinary Pi session becomes a Lead and hands bounded tasks to background Agents without blocking the conversation. The result returns to the conversation that issued the task. At project level a Lead session can enter Manager mode and coordinate several independent Leads. Work is tied to Git branches, so it can be paused, resumed or passed to another Manager. An optional Chief sits above Managers and supervises them. Agents with nested delegation enabled hand their own subtasks further down the chain. Leads message each other, and between machines the messages travel over SSH. Token usage and cost are visible for the current session and every Agent it manages. Agent definitions, models, tools, skills and extensions remain yours. The /herdsman command inside Pi lists available capabilities.
Who it is for. Pi and herdr users who want to run several coding agents in parallel and keep them under control from one session.
Good fit when
- Repository reconnaissance takes time and a scout Agent should study entry points while you keep talking
- A task splits into independent Git branches and each needs its own Lead with a tree of helpers
- An agent should hand out subtasks itself and you want to see how many tokens and how much money each branch used
- Pi sessions on different machines work on one project and need to message each other over SSH
- You already have agent definitions, models and skills to plug in without changing your workflow
Not a fit when
- You work in Claude Code or Codex: the extension is built for Pi and herdr only
- You need one agent in one window: a coordination layer adds nothing
- You need 1.0 stability: before the first release configuration and conventions may change
- Machines are not connected over SSH: discovery and the first message between them need an SSH route
Example request
Use scout to identify this repository's main entry points. Explain how the application starts. Don't change any filesLimitations
- The project is early-stage: releases before 1.0 may break configuration, and migrations are documented in the changelog.
- Chief is still in development: repository provisioning and Manager lifecycle control are not finished.
- Discovery and the first message between machines need an SSH route from the initiator, while replies go over an existing correspondence without reverse SSH.
- Pi and herdr are required, and models come from Pi's configured authentication.
How to disable. Remove the pi-herdsman package from Pi extensions and turn off the herdr integration with Pi. Exact commands depend on the Pi and herdr versions and are described in those projects' docs.
FAQ
What separates Lead, Manager and Chief?
A Lead is an ordinary Pi session that owns the Agents it delegates to. A Manager coordinates several Leads by Git branch and does not implement tasks through Agents itself. Chief is an optional supervisor above Managers.
How do I install Pi Herdsman?
If Pi and herdr are already installed, run pi install npm:pi-herdsman and herdr integration install pi. For a clean machine the repository has install scripts for Linux, macOS and Windows.
Can Agents run inside Agents?
Yes, when nested delegation is enabled for a given Agent. It then hands out its own bounded subtasks, and ownership stays a Lead, Agent, Agent chain.
How do I see what the Agents cost?
The extension shows Pi-native token usage and cost for the current session and every Agent it manages. An active Manager also sees the Leads in the project's current assignments.
Which systems does Pi Herdsman run on?
Linux, macOS and Windows: the repository validates its build in CI on all three. Linux and macOS have a sh install script, Windows a PowerShell one.
Discussion
No questions or reviews yet.
Related
PluginsA package for the Pi agent: async subagents run in parallel in Herdr panes and results return on their own.
A herdr pane that draws an agent swarm as a live graph with attempts, review gates and evidence, so large runs stay readable.
An extension for the Pi agent: one programmable fabric_exec tool calls tools, MCP, agents and workflows from code
Background runs of pi coding agents on your machine by schedule and label, each job in a Docker container with a spending limit.
Personal Pi agent setup with four commands for plan, todos, execution and review, passing state through Markdown session files.
pi-intercom links pi sessions on one machine for one-to-one messages between agents or through the Alt+M shortcut.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Pi Herdsman (this card) | no | 226 | |
| pi-subagents | no | 1,449 | Claude Code-style subagents and orchestration for Pi, without Manager and Chief roles or branch supervision |
| herdr | no | 50,721 | the terminal multiplexer for agents itself, while Herdsman adds delegation inside Pi on top of it |
README in short
The page opens with the Pi and herdr pairing and a demo of the Manager, Lead and Agent chain. It continues with a quick start, a role diagram, a component status table and the roadmap. At the bottom are links to docs on getting started, project orchestration, peer messaging and custom Agent definitions.