pi-herdr

Pi extension for Herdr-visible subagent herds — default-local workers, optional ranked-frontier think, markdown handoff.

Design intent

| Role | Who | | ---- | --- | | Orchestration | Frontier model (parent session) | | Implement / slice | Local seat — private, free, clean per-job context, cap = maxModelConcurrent | | Isolated review / plan / VERIFY | role=think — one job per catalog model; two tasks → one each; next think rotates to the other | | User view / permissions | Herdr panes (watch, focus, accept) |

Requires running inside Herdr (HERDR_ENV=1). Outside Herdr, herd still loads for config/status, but spawn/boot and the herdr tool are inactive.

Install

pi install npm:@itc-steve/pi-herdr

From a local checkout:

pi install /path/to/pi-herdr

Then /reload. Use /herd help for slash usage.

Do not install other herdr packages at the same time (e.g. @ogulcancelik/pi-herdr, pi-custom-herdr). This package vendors the herdr tool and refuses to load if a known competitor appears in Pi settings.

Requirements

• Node.js ≥ 22.19
• Pi coding agent
• Herdr (terminal workspace / agent multiplexer)
• Models listed in config must already be available to Pi (local vLLM/SGLang, Grok CLI, etc.)

Config

Copy herd.json.example to ~/.pi/agent/herd.json (created automatically on first models, run, or journal if missing):

{
  "sessionDir": "~/.pi/agent/herd",
  "maxModelConcurrent": 2,
  "local": {
    "enabled": true,
    "model": "vllm/Qwen/Qwen3.6-27B-FP8",
    "thinking": "medium",
    "preflight": true
  },
  "do": [
    { "model": "grok-cli/grok-build", "thinking": "medium" }
  ],
  "think": [
    { "model": "grok-cli/grok-4.6", "thinking": "high" },
    { "model": "openai-codex/gpt-5.6-sol", "thinking": "high" }
  ],
  "private": { "enabled": false },
  "defaults": {
    "isolation": "none",
    "timeoutMs": 600000,
    "waitForReply": false,
    "requireOutput": true,
    "resultDelivery": "pointer",
    "triggerTurnOnResult": true
  }
}

think[] order is the rank. Put the best frontier first.

do[] is optional: extra non-local models a bare role=do may rotate onto when local seats are full. The local model stays the do head; each do[] model caps at one in-flight job (same as think — it shares the per-model cap, so a think job and a do job on the same model never overlap).

Old easy / medium / hard catalogs still parse: remotes fold into think (hard, then medium, then easy). local.maxStreams, preferOn, and whenFull are ignored. Cap is always maxModelConcurrent.

Field reference

| Field | Meaning | | ----- | ------- | | sessionDir | Run root (runs/, journals, session JSONL) | | maxModelConcurrent | Cap on local seats and on in-flight jobs per exact provider/model | | local | Default implementer: model id, thinking, optional preflight | | do | Optional extra non-local do models. Bare role=do always takes a local seat while one is free; only when local seats are full does it pick a free do[] model (no think-style round-robin past a free local seat) | | think | Ordered frontier catalog for role=think | | private.enabled | Opt-in cloud redaction + private=true spawn (default false) | | defaults.isolation | ignored; writers share the tree (owns= is the isolation) | | defaults.requireOutput | Async spawn must declare output= | | defaults.resultDelivery | pointer (default: path only) or full (paste reply) | | defaults.triggerTurnOnResult | One parent turn when the last in-flight job finishes (default true) |

Jobs resolved to the local model are tagged local: true so parent, kick text, and herd models all see the seat.

How it works

Default-local + optional think

| Spawn | Route | | ----- | ----- | | no role, or role=do | Local. With do[]: local seats full → rotate onto a free do[] model (1 at a time). All full → queue a local seat. Never overflow onto think. | | role=think (aliases: review, plan, architect, verify) | One in-flight per think model. First → think[0]. Second task or second opinion → the other. Both busy → queue think[0] | | model= | That model (local id still takes a local seat) |

Never dump a whole project on one spawn. Decompose. Parent stays on a frontier model for orchestration; workers get a fresh session and a narrow kick.

One-release shim: difficulty=easy\|medium → do, difficulty=hard → think.

Local seat

1. Default spawn claims a local seat (cap = maxModelConcurrent).
2. With do[]: extra do jobs rotate onto a free do[] model once local seats are full. Without do[]: extra do jobs wait for a free seat. Never overflow onto think.
3. Each job gets a fresh sessions/<job>.jsonl.
4. Kick banner: You are a LOCAL worker. One slice…

Private mode (opt-in)

Default off. Set "private": { "enabled": true } in herd.json.

When on, a cloud parent (active model ≠ local.model) sees [PRIVATE:<category>] instead of detected secrets in tool output, shell output, provider requests (including compaction), and herd-result text. The configured local model is trusted and is not redacted. Detection is regex/field-name based (vendored from @spences10/pi-redact, MIT) — not a guarantee; novel formats, assembled values, and secrets inside images can miss.

No auto-spawn. If the current task needs a withheld value, the cloud agent calls:

herd spawn private=true task="…one secret-dependent step…" output=private-check.md

That spawn requires private.enabled and local.enabled=true, claims a normal local seat (FIFO queue if local seats are busy — never overflow to cloud), and rejects role=think / non-local model=. Private workers cannot spawn nested herd jobs. A [PRIVATE:] marker in a non-private spawn is rejected while private mode is enabled — retry with private=true.

The private worker reruns the operation locally. It must not plan the project, inspect unrelated files, spawn agents, or return secret values. Replies/errors back to a cloud parent are redacted again before delivery (and before the 4000-char paste cap). Journal never stores the reply.

Do not use alternate retrieval tools to recover a marker. Do not ask the worker to print the value.

local.model is a trust assertion: if that id is actually a remote endpoint, private mode will treat it as local and skip redaction.

Handoff runs

~/.pi/agent/herd/runs/<date>_<slug>/
  instruction.md   context.md   plan.md   progress.md
  meta.json   journal.jsonl
  sessions/<job>.jsonl
  jobs/…
  <your output=.md files>

Shared context is markdown only — panes do not chat to each other. Each spawn opens a background tab in the parent's current workspace. Job tabs stay open after success so you can watch or intervene in Herdr.

Write lanes

Multi-writer fan-out requires disjoint owns= (and optional forbid=). Put Parallel lanes in plan.md first; the tool rejects overlapping owners.

Completion (pointer batching)

Async jobs are monitored in the background.

• Mid-wave: footer only (herd: N mon +local M) — no parent turn.
• When the last in-flight job finishes: one batched herd-result with short pointers (output=path), not full reply pastes.
• Parent should read the artifact if it needs content — do not reassess the whole task from a pointer.
• Use herd wait / herd collect for a sync barrier. Set resultDelivery=full only if you need reply bodies in-session.

Tools

| Tool | Role | | ---- | ---- | | herd | Assign / abort / steer / status local-first subagents | | herdr | View and control Herdr terminals (workspaces, tabs, panes, worktrees) |

Rule: assign work with herd. Use herdr to view/focus/read — never herdr run into a herd job pane to assign work.

herd actions

| Action | Purpose | | ------ | ------- | | models | Show local seats + ranked think catalog | | status | Active monitors / local seats | | run | create / list / use / show handoff folders | | spawn | Boot a pane, submit task (async needs output=; role=think optional; private=true for secret-dependent local work) | | steer / abort | Nudge or stop a job | | wait / collect | Block until idle / harvest reply | | close / reset | Close panes / clear monitors | | journal | Soft resume log for the active run |

Quick flow

herd run create name=demo goal="Summarize this repo"
herd spawn task="Fill context.md from the repo" output=context.md
herd spawn task="Implement src/client.ts" output=progress-core.md owns=src/client.ts
herd spawn role=think task="Review progress-*.md; note gaps" output=progress-review.md
herd spawn private=true task="One secret-dependent check" output=private-check.md

Exact model override:

herd spawn model=grok-cli/grok-4.6 task="…" output=notes.md

Slash

/herd help
/herd models
/herd status
/herd run create name=<slug> goal="…"
/herd spawn task="…" output=file.md
/herd spawn role=think task="…" output=review.md
/herd spawn private=true task="…" output=private-check.md

herdr (view / control)

Registered only when HERDR_ENV and HERDR_PANE_ID are set (Herdr-managed pane). Actions include workspace/tab/pane lifecycle, read / watch / wait_agent, run / send / stop, worktrees, and notifications. Prefer friendly aliases or ids from herdr list — never invent pane ids.

Skills

Package skills (herd, herdr) teach the launcher default-local vs think and the herd vs herdr split. They install with the package via the Pi skills manifest.

Footer status

While monitors or local streams are active: herd: N mon +local M. Hidden when idle.

Development

npm test

Tests use Node’s built-in runner with --experimental-strip-types (Node ≥ 22.19). Run npm run typecheck for strict TypeScript checks.

Changelog

See CHANGELOG.md.

License

MIT. See LICENSE.