Why it is worth attention

It offers a secure, generic runtime plumbing layer for Herdr agent control, built with execFile to avoid shell injection, and supports both interactive slash commands and programmatic LLM tools.

Who it is for

Pi users who manage Herdr agents and panes
Developers building product-specific loops that depend on Herdr control
Anyone using Pi as an AI coding environment and needing agent lifecycle management

Use cases

Starting and stopping Herdr managed agents with custom arguments
Reading recent output from agent panes for debugging or monitoring
Sending commands or submitting input to running agents
Listing active agents and their pane configurations

Strengths

Secure argument passing via execFile prevents shell injection
Lazy resolution of the herdr binary avoids startup failures on machines without Herdr
Provides both slash commands (for interactive use) and LLM tools (for programmatic use)
Explicit confirmation requirement for dangerous operations like closing terminals

Considerations

Requires Herdr to be installed and configured on the system
Only usable within the Pi ecosystem, not a standalone tool
The stop command requires manual confirmation, which may interrupt automated workflows

README quick start

Bellwether 🐏🔔

Bellwether is a Pi package for managing Herdr agents, panes, and runtime sessions from Pi.

This is deliberately generic runtime plumbing. Product-specific loop control should depend on this package or adapt its commands/tools, not bury Herdr control inside a loop-specific extension.

Install

Install from GitHub:

pi install git:github.com/joelhooks/pi-bellwether

Or use a local checkout:

pi install /path/to/pi-bellwether

For a one-off smoke test without installing:

PI_OFFLINE=1 pi -e /path/to/pi-bellwether --help

Slash commands

/herdr-status — show Herdr client/server status.
/herdr-agents [--panes] — list detected Herdr agents, optionally with panes.
/herdr-start [--cwd PATH] [--workspace ID] [--tab ID] [--split right|down] [--env KEY=VALUE] [--focus|--no-focus] -- — start a managed agent/process.
/herdr-send — send literal text to a Herdr agent target.
/herdr-submit — press Enter in the target agent's pane.
/herdr-read [--lines N] [--source visible|recent|recent-unwrapped] [--ansi] — read recent output.
/herdr-focus — focus an agent target.
/herdr-stop — close the target agent's pane after confirmation.

Targets are whatever herdr agent accepts: terminal ids, pane ids, unique agent names, detected/reported labels, and legacy pane ids.

LLM tools

herdr_status
herdr_list_agents
herdr_start_agent
herdr_send_message
herdr_submit
herdr_read_agent
herdr_focus_agent
herdr_stop_agent

herdr_stop_agent requires confirm: true because it closes a terminal pane. Read/list first, stop second. FFS, don't let the robot blindly close terminals.

Development

npm install --ignore-scripts
npm run check
npm run smoke
pi-notes brain check

The extension uses execFile, not shell strings, so command arguments are passed without shell injection. It lazily resolves the herdr binary when a command/tool runs, so Pi startup does not fail on machines without Herdr installed.

Description

Bellwether 🐏🔔 — Pi package for managing Herdr agents, panes, and runtime sessions from Pi

Related repositories

Similar projects matched by category, topics, and programming language.

TanStack

Featured

router

TanStack Router is a type-safe, data-driven React router with built-in caching, prefetching, and nested layouts, while TanStack Start extends it into a full-stack SSR framework.

Web DevelopmentFrontend Frameworks

14,861

vercel-labs

Featured

scriptc

scriptc compiles ordinary TypeScript into small, fast native executables without needing Node.js, V8, or any JavaScript runtime in the binary.

Developer ToolsCode Quality & Build

1,985

Jakubantalik

Featured

thinking-orbs

A React component library that renders six hand-tuned animated thought orb loading indicators on a plain 2D canvas, with two purpose-tuned sizes and automatic theme detection for AI and agent UIs.

AI & Machine LearningAI Agents

1,191