Pi Herdsman 🐏

The orchestration layer between Pi and herdr.

Pi Herdsman lets your AI coding assistant delegate work to background Agents while your conversation stays interactive, or coordinate larger projects across independent, branch-based Leads. Pi handles model conversations, herdr manages terminal sessions and workspaces, and Herdsman coordinates delegation, ownership, and supervision.

Emergent agentic workflows

Define the boundaries, not the workflow.

Fixed agent pipelines prescribe the next handoff. Pi Herdsman instead lets models decide how to split work, delegate to permitted Agents or Leads, and sequence or parallelize tasks as results arrive. The execution path emerges at runtime, while Herdsman enforces delegation permissions, ownership, project assignments, and supervision.

Specialize Agents by responsibility and compose their execution capabilities through models, instructions, tools, and Pi extensions. Reuse shared expertise as preloaded instructions or on-demand skills. Herdsman coordinates bounded work without owning domain-specific behavior. Bring your own definitions or workflows; see Agent definitions and Coordination.

Demo

Advanced orchestration: a live Manager → Lead → Agent workflow.

Quick start

Linux/macOS:

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iex

Already using Pi and herdr?

pi install npm:pi-herdsman
herdr integration install pi

Start herdr in your project directory, then run pi in its pane. Try:

Use scout to identify this repository's main entry points.
Explain how the application starts.

The Agent works asynchronously and returns its result to your Pi conversation. Use /herdsman to discover controls. See Getting started for prerequisites, model login, and troubleshooting, or Container deployment for Docker Compose.

What Pi Herdsman gives you

• Background Agents. Delegate bounded work without blocking your conversation.
• Parallel and nested delegation. Run independent work concurrently; permitted Agents can delegate their own subtasks.
• Project orchestration. A Manager coordinates durable, branch-based work across independent Leads.
• Explicit authority. Chief, Manager, Lead, and Agent responsibilities have distinct supervision and ownership boundaries.
• Peer communication. Eligible sessions can exchange messages locally and, where supported, across connected machines.
• Usage visibility. Inspect Pi-native token and cost records for owned Agents and, for an active Manager, assigned Leads.
• Your tools, your workflow. Bring your own Agent definitions, Coordinator profiles, models, tools, skills, extensions, and development process.

From one Agent to a project

A normal Pi session is a Lead. It can own Agents, including permitted nested Agents:

You ↔ Lead
      ├─ Agent
      │  └─ Agent
      └─ Agent

For independent project work, an eligible Lead can enter Manager mode. The Manager assigns branch-based objectives to Leads, which direct their own Agent trees:

You ↔ Manager
      ├─ Lead → Agents
      └─ Lead → Agents

An optional Chief supervises Managers and eligible ordinary Leads without an active project Manager. These roles define authority, not a mandatory task sequence. Project assignments remain durable across Manager turnover.

See Coordination for role boundaries and Project orchestration for assignments, recovery, and integration.

Project status & roadmap

Pi Herdsman is pre-1.0. These capabilities are available today:

• Lead & Agent orchestration. Background and nested delegation, result handoffs, and local peer communication.
• Manager orchestration. Branch-based work assignments, supervision, pause/resume, and authorized local integration.
• Chief supervision. Supervises current Managers and eligible ordinary Leads within one herdr runtime.
• Federated peer messaging. Eligible Managers and ordinary Leads can communicate across connected machines, with durable replies.

Current federation limitations: Independent discovery and initiation require an SSH route from the initiating machine; an existing correspondence allows replies without reverse SSH. Different Herdsman builds cannot yet exchange ordinary messages. See Peer communication.

Open proposals: bidirectional initiation over one-way connections (#790), cross-build messaging (#688), and portable repository runtime (#755).

Early-stage project: Pre-1.0 releases may introduce breaking changes. See the changelog for release and migration guidance.

Choose your next step

Browse the documentation index, or jump to:

• Start: Getting started
• Orchestrate: Project orchestration and Coordination
• Customize: Agent definitions
• Integrate: Coordination API and Peer communication
• Contribute: Contributing

Community

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

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

Thanks to everyone who improves Pi Herdsman through code, reports, and investigations. See Community contributors for acknowledgments.

License

Apache License 2.0