Pi Herdsman lets your AI coding assistant delegate tasks to other assistants running in the background, while you continue using your main conversation. Start with one Agent, or coordinate independent work across a larger project.
Pi runs the coding assistants, herdr manages their terminal sessions and workspaces, and Herdsman coordinates their work.
Advanced orchestration: a live Manager → Lead → Agent workflow.
demo.mp4
- Background Agents. Delegate bounded work without blocking the Lead conversation.
- Parallel and nested delegation. Run independent work concurrently and let explicitly enabled Agents delegate their own bounded subtasks.
- Project orchestration. A Manager coordinates durable branch-based work across independent Leads and their Agent trees.
- Direct supervision. Chief, Manager, Lead, and Agent responsibilities stay explicit instead of collapsing into one global controller.
- Peer communication. Leads can message eligible peers locally; unassigned ordinary Leads and Managers can also collaborate across connected machines.
- Owned usage visibility. Inspect Pi-native token usage and cost for the current session and its transitively owned managed Agents. An active Manager also sees the Leads in its current durable project assignments and their owned Agent trees.
- Your workflow stays yours. Bring your own Agent definitions, models, tools, skills, extensions, and development process.
Linux/macOS:
curl -fsSL https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iexAlready using Pi and Herdr?
pi install npm:pi-herdsman
herdr integration install piIn your project directory, start herdr and then Pi inside its pane:
herdr
piIf Pi needs model authentication, use /login. Then try a read-only first task:
Use scout to identify this repository's main entry points.
Explain how the application starts. Don't change any files.
The Agent works independently and sends its result back to the conversation that delegated the task. Discover Agent management and other capabilities with:
/herdsman
See Getting started for prerequisites and troubleshooting.
A normal Pi session is a Lead. It owns the Agents it delegates:
You ↔ Lead
├─ Agent
│ └─ Agent
└─ Agent
For independent project work, an eligible Lead can enter Manager mode. Managers coordinate Leads instead of implementing through Agents themselves:
You ↔ Manager
├─ Lead → Agents
└─ Lead → Agents
A Chief is an optional runtime-wide supervisor above Managers. Without an active Manager for a project, Chief can directly supervise its ordinary Leads.
The important boundaries are:
supervision: Chief → Manager → Lead
ownership: Lead → Agent → Agent
Project work is durable by Git branch. It does not belong to the Manager session that happened to start it, so assignments can be paused, resumed, or retired across Manager turnover.
Manager-created project Leads are dedicated Managed Lead sessions: identity stays
with the exact Pi session, while only a current project assignment authorizes
execution. Unavailable or retired assignments never enable ordinary Lead tools.
Use native Pi /fork or /clone for independent ordinary continuation with copied
history, not a separate checkout or fresh process configuration. See
Project orchestration.
See Coordination for the mental model and Project orchestration for the Manager workflow.
| Goal | Start here |
|---|---|
| Install and delegate your first task | Getting started |
| Run independent branch-based project work | Project orchestration |
| Communicate with other Pi sessions | Peer communication |
| Understand roles, ownership, and authority | Coordination |
| Customize Agents | Agent definitions |
| Build against the model-facing tools | Coordination API |
| Deploy an SSH-ready environment | Container deployment |
| Contribute to Pi Herdsman | Contributing |
Questions, workflows, examples, and ideas are welcome in GitHub Discussions.
For reproducible bugs and concrete actionable work, use GitHub Issues.