Herald

A Paseo plugin that tells you, out loud, when one of your agents needs you.

When an agent asks a question, pauses for permission, wants a plan approved, finishes its turn, or fails, Herald has a small helper agent write one spoken sentence about it — what is being asked and the choices, or what was done and whether anything is left — and the Paseo app on your desk speaks it. A Herald panel in the sidebar lists every agent waiting on you with that sentence. Tap a row to open that session, or the speaker beside its title to hear the sentence again. The Herald row in the sidebar counts who is waiting; tap the number for a quick list, and pick one to jump to its card.

The sentence is in the conversation too

Every announced event also leaves a card in the agent's own transcript, right where the turn or the question happened, with a play icon to hear it again. It is written as soon as the event lands, so it reads "Writing the summary…" for the second or two the helper takes.

What you need

• Paseo 0.11 or newer, on the daemon and on the device running the app.
• Speech comes out of the device running the Paseo app, not the daemon machine. The voice, by default, is the daemon Mac's: it renders each sentence with say and the app plays the audio, so you hear the Mac's voices rather than a browser's. If the daemon is not a Mac, the browser's own voice is used. The desktop app speaks on its own. A browser tab speaks once you have pressed Test voice in the panel (browsers do not let a page play sound until it has been tapped). Phones cannot speak from a plugin yet; Herald can vibrate instead, and Paseo's own notifications already carry the text there.
• Summaries are written by a helper agent through whichever provider you pick, Claude Haiku 4.5 by default. Each event is one short turn of that model; the helper appears briefly under the agent it describes and is deleted once its sentence is written, so it leaves nothing in your history.
• The paseo command, on the daemon's PATH. It is what deletes the helpers, and it is the only thing Herald needs it for — without it, helper sessions simply pile up.

Install

paseo plugin install npm:@gpambrozio/paseo-herald

That is the shortest route on Paseo 0.11 or newer, which installs plugins straight from npm; add @<version> to pin one. On Paseo 0.9 or 0.10, install the last release that supports them: paseo plugin install npm:@gpambrozio/paseo-herald@0.5.1. On 0.8, install the last release that supported it from this repository instead:

paseo plugin add gpambrozio/paseo-plugins --path herald --ref herald/v0.3.0

Pin a repository install with --ref herald/v<version>. To hack on it, clone the repository and paseo plugin install "$PWD" from this folder after npm install and npm run typecheck.

Settings

Settings › Plugins › Herald — the gear in the panel's header, Herald settings from the Command Center, or the settings screen itself.

• Speech — the master switch; whether the desktop app, browser tabs, and phones act on it; the voice source (the daemon Mac's say voices, or this device's browser voice), which voice, the speed; a test button. To add Mac voices, install them on the daemon Mac under System Settings › Accessibility › Spoken Content. These are shared by every device connected to the daemon, and each device follows its own switch. Mute here in the panel silences just the device you are on until the app restarts.
• Summaries — the model that writes them, the prompt they are written from, whether the helper sessions are deleted, and which kinds of event are announced: questions, plan approvals, tool permissions, finished turns, errors. A kind that is switched off still appears in the panel, without a summary and without being spoken.
• Agents started by another agent — off by default. A subagent, or a worker a FirstMate first mate dispatched, reports to the agent that started it: Paseo tells that agent when it finishes, fails or needs a permission, and you hear the parent's announcement, in its words, rather than two. Such an agent is still listed in the panel, like a switched-off kind. Turn it on to hear both. Paseo tells the parent only about the task it handed over, so while this is off two things go unannounced by anyone: anything that agent does after its first task has finished or failed — a prompt you send it yourself, say — and every agent started without asking to be told when it finishes.

The prompt

Summary prompt opens the whole prompt the helper is given, to edit however you like — shorter sentences, another language, more about what matters to you for a finished turn than for a question. Herald fills in the parts that change per event wherever you put them:

A line whose placeholder has nothing to fill it for that event is left out whole, so keep a label and its placeholder on the same line — Detail: {{detail}} simply disappears when there is no detail. Anything else in double braces is sent as you typed it. Restore the default brings the original prompt back, and an empty prompt is the default one.

The default prompt ends by asking for a small JSON object, which is what Herald reads the sentence out of. You can drop that — Herald then speaks whatever the model replies, trimmed to the first 45 words — but the result is less predictable, so the editor says so.

Helper sessions

A helper agent is a session like any other, so left alone every summary would put one in your history. Herald deletes each one the moment its sentence is written, and shortly after the daemon starts it clears any that were left over — the ones from before you upgraded, and any orphaned by a plugin reload or a daemon that stopped mid-summary. A summary still being written is never touched.

Turn Delete the helper when it is done off under Summaries to keep them instead, which is worth doing when a summary comes out wrong and you want to read what the helper was actually asked.

What the helper sees

With the default prompt, for a finished turn the helper is given what the agent said after your last message, and your last message. For a question or permission it is given the question and the choices, or the command. That text goes to the model you chose, through your own provider credentials, the same way the agent's own work does.