pi-herdr-squad

Visible, strictly read-only investigation squads for Pi running inside Herdr.

The package creates a dedicated Herdr tab with one to four interactive Pi children, assigns exclusive scopes, waits for structured reports, and gives the parent agent the evidence needed to synthesize a result.

Requirements

• Pi with extension, skill, and prompt-template support.
• A Pi session running in a Herdr-managed pane (HERDR_ENV=1).
• Herdr's managed Pi state integration installed. Herdr normally manages herdr-agent-state.ts itself.

Install

Install from npm:

pi install npm:pi-herdr-squad

For local development from this checkout:

pi install /absolute/path/to/pi-herdr-squad

Then start a new Pi session or run /reload.

First use

1. Run Pi inside a Herdr-managed pane.
2. Use /login to authenticate, if needed, and /model to verify the desired model.
3. Install the package, then start a new Pi session or run /reload.
4. Start a simple squad, for example /herdr-squad 1 inspect the package entry point.

Use

Let the parent choose a conservative agent count:

/herdr-squad auto compare frontend and backend validation

Use an exact count:

/herdr-squad 3 investigate checkout failures across runtime code, tests, and configuration

Natural-language requests also load the skill when they explicitly request a Herdr squad or parallel subagents:

Start a two-agent Herdr squad to compare client and server validation.

The parent plans non-overlapping scopes, then calls herdr_squad_start, herdr_squad_wait, and herdr_squad_collect sequentially. Children remain visible in their Herdr tab after collection.

Child model selection

The model precedence is:

1. An explicit model requested for one squad through herdr_squad_start.model.
2. Trusted project config at .pi/herdr-squad.json.
3. Global config at ~/.pi/agent/herdr-squad.json.
4. Pi's normal default model when no squad model is configured.

Global configuration (~/.pi/agent/herdr-squad.json):

{
  "defaultModel": "openai-codex/gpt-5.6-terra"
}

Trusted project configuration (.pi/herdr-squad.json) uses the same shape. A trusted project can bypass the global squad model and use Pi's normal default:

{
  "defaultModel": null
}

Configuration is read whenever a squad starts, so changing the JSON file does not require /reload. Untrusted project configuration is ignored.

To override configuration for one investigation, request the exact model explicitly:

Start a two-agent Herdr squad using openai-codex/gpt-5.6-terra to audit the auth migration.

The selected model applies to every child in that squad.

Choose and verify a model

Copy the exact identifier recognized by Pi, generally in provider/model form. List available identifiers with:

pi --list-models

In interactive Pi, use /login to authenticate and /model to inspect or select available models. Pi also accepts compatible suffixes such as provider/model:thinking; squad configuration passes the value unchanged to pi --model.

Prefer the provider-qualified identifier shown by Pi. A bare name such as gpt-5.6-terra can be ambiguous or resolve against an unintended provider; use openai-codex/gpt-5.6-terra when that is the identifier Pi shows. Pi remains responsible for resolving the identifier, credentials, and model availability; the squad extension does not preflight or duplicate Pi's model registry.

Read-only boundary

Every child receives exactly these active tools:

read, grep, find, ls, herdr_squad_report

Children do not receive bash, edit, or write. The report tool writes only an extension-owned JSON report under a private temporary run directory; it cannot modify the shared checkout.

Task text is stored in mode-0600 prompt files and is never interpolated into shell commands. Tab and pane identities are revalidated before terminal fallbacks are read.

Package contents

• agent/extensions/herdr-squad/ — parent orchestration and child reporting.
• agent/skills/herdr-squad/SKILL.md — delegation and synthesis policy.
• agent/prompts/herdr-squad.md — /herdr-squad entry point.

Development checks

npm run check
npm run pack:check

The package has no third-party runtime dependencies. Pi-provided APIs are declared as peer dependencies.

License

MIT