home
cli · bash 3.2 · apache-2.0

herald

Cross-pane messaging for herdr. Two agent sessions in different panes, tabs or workspaces exchange messages directly, instead of a human relaying between them. A delivery budget runs out and pauses for review.

install
brew tap budhash/tools
brew install herald

Or without Homebrew:

curl -fsSL https://github.com/budhash/herald/releases/latest/download/install.sh | bash

One file, no runtime dependencies beyond herdr and jq. The companion agent skill is embedded in the script, so herald skill install works however herald got onto the machine.

what it does
session A (w1:p1)                       session B (w2:p3)
    |  herald send w2:p3 --body-file notes.md   |
    |------------------------------------------>|  submitted, and verified
    |                                           |
    |<------------------------------------------|  herald send w1:p1 "done"
    |                                           |
    [paused] budget exhausted -> waiting for the human

A channel is the unordered pair of pane ids, so both sides share one transcript and one budget. "Delivered" means submitted and verified: herald confirms the peer actually started working. If the text landed in the prompt but never submitted, it says so and exits 3 rather than reporting success.

commands
herald lslist running agent sessions: pane · status · directory
herald send <peer>record and deliver, verifying submission
herald read <peer>the shared transcript
herald peek <peer>the peer's raw output, not just what it heralded
herald rosterevery channel: budget · age · submit state
herald nudge <peer>re-submit a stuck message (costs no budget)
herald resume <peer>grant budget and flush the queue
why the budget exists

The budget is enforced in the CLI, not by agent goodwill. At zero, the next send is recorded but not delivered, and only herald resume releases it. The pause is where a human reads the transcript and decides whether to continue.

Source & documentation ↗

About herald

herald lets two agent sessions running under herdr exchange messages directly, instead of a human copying output from one pane into the other.

How it works

Delivery is a prompt submission, not an API call: herald types the message into the peer's prompt and then verifies the peer actually started working on it. Channel state — transcript, queue and budget — lives under ~/.local/state/herald.

Scope

Point-to-point only, and both panes must be on the same herdr server. It is not a group chat and not a cross-host message bus.

Privacy

This page is static — it has no scripts beyond the About dialog and sends nothing anywhere. herald itself runs entirely on your machine, over herdr's local socket.

Source · Apache-2.0 licensed