Pi Herd 🐏

Herdr-backed subagents for Pi with bounded delegation, reusable workers, steering, owner clarification, and lifecycle-safe orchestration.

Install

pi install npm:pi-herd

Herdr owns physical worker lifecycle and placement. The extension mailbox owns assignment and completion coordination. Pi owns session and turn state. The logical worker label is the public live-control identity.

Requirements

• Herdr >=0.8.0
• Pi >=0.84.2 <0.85.0 (the version range tested for this release)
• Herdr Pi integration version 2 or newer
• Node >=22.19.0

Install or refresh the Herdr Pi integration:

herdr integration install pi
herdr integration status

The package manifest loads the bundled extension and exposes the optional subagents skill.

The root Pi supervisor must run inside Herdr.

Quick start

Ask the supervisor to inspect the available workers first:

{ "action": "list" }

Create a fresh implementation worker:

{
  "action": "assign",
  "agent": "implementer",
  "task": "Implement the approved change"
}

Assignments are asynchronous. Continue only with work that does not depend on the active worker, or end the turn normally. Worker completion or attention resumes the owning controller automatically.

For the first complete walkthrough, see Getting started.

What the package provides

• Fresh, reusable, resumed, and forked managed Pi workers.
• Exact-label worker control with durable assignment/result correlation.
• One bounded delegation level through per-agent subagents allowlists.
• Worker-to-owner clarification through ask_owner and owner reply.
• Global Markdown agent overrides without copying complete bundled definitions.
• Strict whole-line body @file references resolved from the declaring definition.
• TUI status projection and root-only /subagents human commands.
• Bounded startup diagnostics, fail-closed identity checks, and ownership-safe cleanup.

The bundled portable roster is implementer, researcher, reviewer, scout, and worker. Operator-local tools, extensions, skills, models, and additional instructions belong in global definitions.

Documentation

Start at the documentation index.

Learn

• Getting started
• Workers and identity
• Lifecycle
• Delegation

Configure and operate

• Agent definitions
• Customizing bundled agents
• Handoffs and files
• Recovery

Reference

• subagent API
• ask_owner API
• Agent-definition schema
• Worker states
• /subagents commands
• Configuration
• Status widget
• Errors

Development

• Validation
• Smoke testing
• Documentation maintenance

Human commands

Interactive root supervisors expose:

/subagents agents
/subagents overrides
/subagents placement [tab|split]
/subagents stop

These commands are human-facing. The structured model interface is the subagent tool.

Repository validation

prettier . --write
npm run check
git diff --check

See Development validation for the full gate.