@weshipwork/pi-herd

Read-only Herdr transcript mirrors for Pi Subagents.

Packages

Package details

extension

Install @weshipwork/pi-herd from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@weshipwork/pi-herd
Package
@weshipwork/pi-herd
Version
0.1.0
Published
Jun 15, 2026
Downloads
not available
Author
nodnarbnitram
License
MIT
Types
extension
Size
28.1 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions/herd.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@weshipwork/pi-herd

Read-only Transcript mirror plumbing for Pi Subagents in Herdr.

This package is the v1 mirror-mode tracer bullet from the project ADRs:

  • Subagents still run in the Delegator Pi process.
  • A Delegator-side bridge serves structured mirror events over one Unix socket.
  • pi-herd-viewer connects from a Herdr pane and renders a read-only transcript/status stream.

Viewer

pi-herd-viewer --socket /path/to/pi-herd.sock --agent-id <subagent-id>

The current tracer bullet supports:

  • a read-only observation-source interface for Subagent snapshots and live updates;
  • a forked pi-subagents mirror-service adapter shape;
  • a Delegator-side MirrorBridge that forwards those updates to MirrorServer;
  • initial snapshots, assistant text deltas, and status updates in the viewer stream.
  • a Pi extension entrypoint that starts a session-scoped mirror runtime when an observation source is installed;
  • Herdr pane launch for pi-herd-viewer mirrors.

Full chronological transcripts, tool folding, and scroll/focus keybindings are later slices.

Pi extension integration

./extensions/herd.ts starts only inside Herdr (HERDR_ENV and HERDR_PANE_ID) and requires a read-only observation source from the forked pi-subagents runtime:

import { installPiHerdObservationSource } from "@weshipwork/pi-herd/extensions/herd";

installPiHerdObservationSource(source);

The expected fork seam is represented by PiSubagentsMirrorService in src/pi-subagents-observation-source.ts.