pi-herdsman

Pi Herdsman 🐏

The orchestration layer between Pi and herdr.

Pi Herdsman turns independent Pi sessions into a coordinated agent system, from one background Agent to parallel branch-based project work. Pi owns each coding-agent conversation; herdr owns processes, panes, workspaces, and worktree placement; Herdsman connects them through delegation, ownership, supervision, and project orchestration.

Demo

Realtime live demo of a manager > lead > agent workflow.

What Pi Herdsman gives you

• 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.
• 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.

Quick start

On Linux or macOS, install the released Pi, herdr, and Pi Herdsman stack:

curl -fsSL https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.sh | sh

See Getting started for the tested runtime baselines and how the bootstrap handles newer Pi and herdr versions.

If you already manage Pi and herdr yourself:

pi install npm:pi-herdsman
herdr integration install pi

Start herdr in your project, then start Pi inside its pane:

herdr
pi

Delegate naturally:

Use scout to inspect the authentication flow.

The Agent runs asynchronously while the Lead conversation stays available. Open the human Agent-management surface at any time with:

/agents

It also exposes Session stats for the current Pi session and its owned Agent sessions; in active Manager mode, it includes current assigned project Leads and their owned Agent trees.

See Getting started for prerequisites, configuration, observability, and the complete first-use path.

From one Agent to a project

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.

Choose your next step

Community

Questions, workflows, examples, and ideas are welcome in GitHub Discussions.

For reproducible bugs and concrete actionable work, use GitHub Issues.

License

Apache License 2.0