pi-pier

[!IMPORTANT] This package is the whole of pier: a pi extension. It talks to herdr-core (hc) for terminals and status, and the optional Herdr app displays those terminals. Without a core terminal (HC_TERMINAL_ID / HC_TERMINAL_SOCKET) you still get todo_write / ask_user_question; subagent / terminal are not registered.

pier = pi × herdr — a pi extension that fuses coding agent sessions with terminals managed by herdr-core.

pi-pier fills two gaps pi deliberately leaves open — the todo list loop and interactive subagents — using core terminals as the visual and interaction substrate. Outside a core terminal it loads only the todo loop.

Install (this pi half)

pi install npm:pi-pier

Or from git (monorepo root, same content):

pi install git:github.com/July24/pier

Then install herdr-core (required for subagents) and, optionally, the Herdr app:

curl -fsSL https://releases.herdr.dev/core/install.sh | sh   # hc ≥ 0.1.16
# Herdr app: https://herdr.dev/

Or install everything at once with the one-shot installer from the monorepo:

git clone https://github.com/July24/pier && cd pier
node install.mjs        # user mode: installs the pi extension

The installer verifies node / pi / hc versions and prints an informational line for herdr-app.

What you get

Tools

Commands

/dashboard was removed in the core migration — the app-side plugin and its panels no longer exist.

Behaviors

• Human-in-the-loop: every subagent is a visible terminal the Herdr app lists under its master (a pane only with tab) — peek at it anytime to talk directly (fix bugs, answer its ask_user_question). Status reaches the app through pi's native OSC 7501 report; pier does not synthesize it.
• Delegation identity: the worker knows who delegated it — spawn env (PI_HERDR_DELEGATION) replays from the session's own first-frame entry; its system prompt carries a pier-delegation section (identity + delivery contract), and the transcript opens with an "⟵ delegated by master …" card
• Blocking dialogs report blocked: pi's native OSC 7501 reporter covers the inherently blocking ctx.ui dialogs (select / confirm / input / editor) and permission dialogs from any extension; since pi 1.5 pier opens its ui.custom ask picker with blocked: { kind: "question" }, so pi reports it too and restores the run state when it closes. pier writes no status itself.
• Readable transcript: pier's own session entries (todo edits, subagent/terminal registries, delegation) and its reminder messages render as compact cards instead of raw JSON
• Soft locks: write paths publish per-terminal pier.lock.<hash> labels; conflicts warn (default) or block (PI_HERDR_WRITE_LOCK=1) instead of racing silently. Warnings name every holder — the audience split is: agent reads its own tool-result warning, human reads /locks (or hc get <terminal> --json for the raw label table). write/edit only — bash writes are not covered
• One model for the whole tree: workers are spawned with the master's current model (--provider/--model from the master's live model, so a /model switch carries over); no role profiles or tool gates
• Settlement notices folded: background subagent completions inject between turns (max 3 shown, rest collapsed) instead of flood-filling at run end

Scope & degradation

This extension mutates the pi session even outside a core terminal. After pi install npm:pi-pier:

Session JSONL custom types (pi-herdr.todo-edit, .subs, .terminals, .todo-read, .todo-reminder, …) persist across /resume even without core.

Plugin conflicts

pi overwrites tools/commands by name; event listeners stack.

Do not install alongside (same-name overwrite → wrong handler, split JSONL):

• @nguyenquangthai/pi-todo — todo_write + overlay
• @josephyoung/pi-ask-user-question — ask_user_question
• pi-herdr-subagents — subagent + herdr panes

Soft conflict (two orchestrators / two injectors — the agent “talks to itself”):

• @tintinweb/pi-subagents (Agent)
• @minhduydev/pi-subagents (task)
• any other extension that calls setActiveTools, ui.custom overlay, before_agent_start, or sendUserMessage/sendMessage followUp

Status ownership: pi's native OSC 7501 reporter is the only status source; pier never writes terminal status. Do not add a second OSC 7501 reporter for the same terminal.

Requirements

• Node ≥ 22
• pi ≥ 1.5.0 (@earendil-works/pi-coding-agent) — the native OSC 7501 reporter is required
• herdr-core hc ≥ 0.1.16 — required for subagents / terminal integration; curl -fsSL https://releases.herdr.dev/core/install.sh | sh
• Herdr app (optional) — display only

The last TUI-compatible release is 0.4.3. The core-only cutover is the feat/core-app-migration branch.

Development

git clone https://github.com/July24/pier && cd pier
npm install --ignore-scripts
npm test   # typecheck + node --test

See the monorepo README for design principles and the one-shot installer.

License

MIT