{"id":"herald","repo":"gpambrozio/paseo-plugins","url":"https://github.com/gpambrozio/paseo-plugins/tree/main/herald","name":"herald","description":"A [Paseo](https://paseo.sh) plugin that tells you, out loud, when one of your agents needs you.","categories":["productivity","monitoring"],"platforms":["macos"],"caveats":["Doesn't play on mobile, only tested on MacOS"],"images":["https://raw.githubusercontent.com/gpambrozio/paseo-plugins/216477edf9bce174365cf50b194c08e8d32aa4a4/herald/docs/panel.png","https://raw.githubusercontent.com/gpambrozio/paseo-plugins/216477edf9bce174365cf50b194c08e8d32aa4a4/herald/docs/timeline-card.png"],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":true,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-09-18T07:57:32.453Z","addedAt":"2026-09-18T10:53:43+03:00","path":"herald","version":"0.2.0","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-18T07:55:34.572Z","commit":"216477edf9bce174365cf50b194c08e8d32aa4a4"},"license":"MIT","paseoVersionRequirement":">=0.8.0","manifest":{"id":"herald","requirements":{"paseo":">=0.8.0"}},"repoMeta":{"stars":7,"defaultBranch":"main","pushedAt":"2026-09-17T19:01:54Z"},"owner":{"login":"gpambrozio","avatarUrl":"https://avatars.githubusercontent.com/u/672135?v=4"},"installNotesHtml":"
paseo plugin add gpambrozio/paseo-plugins --path herald\n
\n

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

","readmeText":"# Herald\n\nA [Paseo](https://paseo.sh) plugin that tells you, out loud, when one of your agents needs you.\n\nWhen an agent asks a question, pauses for permission, wants a plan approved, finishes its turn, or\nfails, Herald has a small helper agent write one spoken sentence about it — what is being asked and\nthe choices, or what was done and whether anything is left — and the Paseo app on your desk speaks\nit. A **Herald** panel in the sidebar lists every agent waiting on you with that sentence. Tap a row\nto open that session, or the speaker beside its title to hear the sentence again.\n\n![The Herald panel: three finished agents, each headed by its workspace title with a speaker icon\nbeside it and how long ago it finished, then what the agent was last asked, its own last line, and\nin italics the sentence Herald wrote about it. Mute here, Test voice, a refresh button and a settings\nbutton sit in the header, next to a badge counting the agents waiting.](docs/panel.png)\n\n## The sentence is in the conversation too\n\nEvery announced event also leaves a card in the agent's own transcript, right where the turn or the\nquestion happened, with a play icon to hear it again. It is written as soon as the event lands, so it\nreads \"Writing the summary…\" for the second or two the helper takes.\n\n![A Herald card in an agent's conversation: a small panel headed \"Herald · Finished\" with a play\nicon, and under it, in italics, the sentence written about the turn that just ended. The agent's\ncomposer sits below it.](docs/timeline-card.png)\n\n## What you need\n\n- Paseo **0.8.0 or newer**, on the daemon and on the device running the app.\n- Speech comes out of the device running the Paseo app, not the daemon machine. The voice, by\n default, is the daemon Mac's: it renders each sentence with `say` and the app plays the audio, so\n you hear the Mac's voices rather than a browser's. If the daemon is not a Mac, the browser's own\n voice is used. The **desktop app** speaks on its own. A **browser tab** speaks once you have pressed\n *Test voice* in the panel (browsers do not let a page play sound until it has been tapped). **Phones\n cannot speak** from a plugin yet; Herald can vibrate instead, and Paseo's own notifications already\n carry the text there.\n- Summaries are written by a helper agent through whichever provider you pick, Claude Haiku 4.5 by\n default. Each event is one short turn of that model; the helper appears briefly under the agent it\n describes and is archived when it finishes.\n\n## Install\n\n```bash\npaseo plugin add gpambrozio/paseo-plugins --path herald\n```\n\nPin a release with `--ref herald/v`. To hack on it, clone the repository and\n`paseo plugin install \"$PWD\"` from this folder after `npm install` and `npm run typecheck`.\n\n## Settings\n\n**Settings › Plugins › Herald** — the gear in the panel's header, *Herald settings* from the Command\nCenter, or the settings screen itself.\n\n- **Speech** — the master switch; whether the desktop app, browser tabs, and phones act on it; the\n voice source (the daemon Mac's `say` voices, or this device's browser voice), which voice, the\n speed; a test button. To add Mac voices, install them on the daemon Mac under System Settings ›\n Accessibility › Spoken Content. These are shared by every device connected to the daemon, and each\n device follows its own switch. *Mute here* in the panel silences just the device you are on until\n the app restarts.\n- **Summaries** — the model that writes them, the prompt they are written from, and which kinds of\n event are announced: questions, plan approvals, tool permissions, finished turns, errors. A kind\n that is switched off still appears in the panel, without a summary and without being spoken.\n\n### The prompt\n\n*Summary prompt* opens the whole prompt the helper is given, to edit however you like — shorter\nsentences, another language, more about what matters to you for a finished turn than for a question.\nHerald fills in the parts that change per event wherever you put them:\n\n| Placeholder | Filled with |\n| --- | --- |\n| `{{agent}}` | What the work is called: the agent's title, or its workspace's. |\n| `{{workspace}}` | The workspace's title, or the folder name when it has none. |\n| `{{folder}}` | The last part of the agent's working directory. |\n| `{{event}}` | A sentence saying why the agent is waiting. |\n| `{{headline}}` | The one line Herald builds without a model: the question, the command, \"Finished\". |\n| `{{detail}}` | The choices, the command, or the start of the final message. Often empty. |\n| `{{request}}` | What you last asked this agent for. Empty when the agent paused without one. |\n| `{{output}}` | What the agent said since that message. Empty for a pause. |\n\nA **line** whose placeholder has nothing to fill it for that event is left out whole, so keep a label\nand its placeholder on the same line — `Detail: {{detail}}` simply disappears when there is no detail.\nAnything else in double braces is sent as you typed it. *Restore the default* brings the original\nprompt back, and an empty prompt is the default one.\n\nThe default prompt ends by asking for a small JSON object, which is what Herald reads the sentence\nout of. You can drop that — Herald then speaks whatever the model replies, trimmed to the first 45\nwords — but the result is less predictable, so the editor says so.\n\n## What the helper sees\n\nWith the default prompt, for a finished turn the helper is given what the agent said after your last\nmessage, and your last message. For a question or permission it is given the question and the choices, or the command. That\ntext goes to the model you chose, through your own provider credentials, the same way the agent's own\nwork does.\n"}