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

| Tool | Purpose | |---|---| | todo_write | Full-replacement todo list. Session JSONL is the single source of truth; correct rollback on branch switches. Progress shows in the resident widget and /todos; the list is mirrored into a pier.todo terminal label only so the master can rebuild worker summaries (no pane-title projection). /todos command to view/edit/unblock | | subagent | Delegate self-contained subtasks to an isolated pi session in its own herdr-core terminal, running the master's current model. Actions: spawn (default; foreground / parallel / background), wait (block until a worker settles or needs a human), list, send, interrupt, resume, output (incremental preview of a running subagent's terminal output), help (the full manual — placement, isolate, ledger — kept out of the per-request description). Every spawned task gets a stable slug: outputs print slug@paneId, and agentId accepts the slug, the terminal id, or the combined form | | terminal | Persistent interactive shells in dedicated herdr-core terminals. Actions: open, send, read, signal, close, list |

Commands

| Command | Purpose | |---|---| | /todos | Show the todo list, or edit it: /todos done\|drop\|rm\|unblock <fuzzy match> | | /pier-tree | Master only: the full delegation tree — your complete todo list plus every running subagent's full list (live-pushed over the pipe) and settled nodes with ages. Opens as an in-pi overlay (ui.custom; esc/q closes, live refresh while open). Bare pi / RPC mode falls back to the in-pane notify view. The resident widget stays one line per agent and hides entirely once the self list is fully completed (D113/D114) | | /locks | Show write locks held by this terminal and by live terminals — the human/operator view of the pier.lock.<hash> labels (herdr-core only). Agents see the holders inside their own write warnings; raw labels are readable via hc get <terminal> --json | | /pier-config | Read-only configuration guide over three planes (efficiency / pi / env): bare call = index + hands a guided change to the agent; show [plane\|all] = effective value + source (env > workspace > user > default); check = validate all planes; doc [path] = write a report |

/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:

| Surface | Bare pi (no HC_TERMINAL_ID / HC_TERMINAL_SOCKET) | Inside herdr-core | |---|---|---| | todo_write, /todos, widget, anti-freeze, stop reminder | live | live | | ask_user_question | live (TUI picker for single and multi; host select dialog / typed prompts as RPC fallback) | live + blocked report while the overlay is open | | Blocked reporting for blocking ctx.ui dialogs (select/confirm/input/editor) | live | live | | Hidden inject (before_agent_start todo-read; settle reminder) | live | live | | subagent, terminal | not registered | live | | /locks, write-lock on write/edit | not installed | live | | /pier-config (read-only config guide over 3 planes) | live | live | | slim-frame overlay, pipe, isolate worktree | off | live |

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