Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Herald: deliver a message in person
A notification is a badge you have to notice, in a tray you have to open, competing with forty others. Herald is the opposite: a 3D character walks into the corner of the page, looks at the person using it, and tells them, with a link to the thing it is about.
It ships as four pieces that work independently and compose:
| Piece | Where | What it is |
|---|---|---|
| The library | herald-sdk/, published as @three-ws/herald |
The rules engine and the presenters. Works on any site, with or without a bundler. |
| The rail | POST /api/herald/announce, GET /api/herald/stream |
Anything that can make an HTTPS request reaches the browser tab you have open. |
| The CLI | npx @three-ws/herald |
herald watch -- npm test announces when your build finishes. |
| The MCP server | packages/herald-mcp/ |
An AI agent tells its human something in person. |
Try all of it at three.ws/herald, which runs the real library in your own tab: change the rules, send a message, and watch the engine decide.
three.ws delivers its own notifications the same way. That path has its own
client (src/notification-herald.js, wired to
the bell inbox and gated by the per-category avatar channel in the preference
center, see
Notifications), and
it shares this one's body: both hand the line to the walk companion's
announce(). The library here is the general form, for any site and any feed.
The idea
Every alerting surface we have is a queue competing for the same half-second of attention: a red dot, a rectangle that slides in, a phone buzz. They are the same shape, they are all ignorable, and the important ones look exactly like the noise.
A person walking up to your desk is not ignorable, and nobody has to design an unread state for it. Herald is that, on the web, for the handful of events per day that deserve it. Everything in the library exists to keep the interruption rare enough to stay effective, which is why most of this page is about what it refuses to deliver.
Quick start
npm install @three-ws/herald
# optional: the 3D body. Without it, deliveries use the accessible card.
npm install @three-ws/walk three
The avatar presenter finds a companion in three places, cheapest first: one you
pass in (createHerald({ companion })), one already live on the page
(window.__walkCompanion, which is what every three.ws page has), or a module
URL you name (avatarOptions: { walkModule: '/walk-companion.js' }). None of
them is a static import, so the optional 3D body can never break a build.
import { createHerald } from '@three-ws/herald';
const herald = createHerald({
rules: { minImportance: 70, quietHours: [22, 7] },
voice: 'auto',
});
herald.announce({
text: 'Payment received from Acme',
from: 'Stripe',
importance: 85,
url: '/payments/inv_123',
});
With no bundler at all:
<script type="module">
import { createHerald } from 'https://three.ws/herald.js';
createHerald().announce('Deployed to production');
</script>
/herald.js is served with permissive CORS, exactly like the <agent-3d>
bundle, so it can be imported from any origin.
What it refuses to deliver
announce() returns a verdict rather than a promise of delivery, and every
message that does not reach a human comes back with a reason.
herald.announce({ text: 'someone viewed your profile', importance: 10 });
// { action: 'drop', reason: 'below-importance-floor', message: {...} }
Dropped (will never be delivered): empty, muted, duplicate, stale,
below-importance-floor.
Held (delivered once the thing blocking it clears): delivering-another,
window-not-focused, rate-limited, quiet-hours.
Held messages are re-examined when the rate window drains, quiet hours end, or
the tab comes back. A burst past batchSize is collapsed: the most important
few are said, and the rest become one "N more messages waiting" line.
| Rule | Default | What it does |
|---|---|---|
minImportance |
50 |
The interrupt floor. |
freshnessMs |
15 min |
Older than this is history, and history belongs in an inbox. |
dedupeTtlMs |
6 h |
The same key is said once, however often a feed repeats it. |
quietHours |
null |
Local [start, end), wrapping past midnight. |
quietHoursMinImportance |
90 |
What still gets through the night. |
maxPerWindow / rateWindowMs |
4 / 60 s |
The rate limit on interruptions. |
focusOnly |
true |
Hold while the tab is in the background. |
batchSize |
2 |
Said per burst before the rest collapse. |
Scoring is pluggable, and the highest opinion wins:
herald.rule((m) => (m.from === 'oncall' ? 100 : undefined));
herald.rule((m) => (/\bfailed\b/i.test(m.text) ? 90 : undefined));
Sources
A source is { name, start(emit) => stop }. Three ship with the library, and
writing one for a feed nobody here has heard of is about five lines.
import { createHerald, pollSource, sseSource, railSource } from '@three-ws/herald';
const herald = createHerald();
// Any JSON endpoint. Polling stops while the tab is hidden.
herald.source(pollSource({
url: '/api/alerts',
intervalMs: 30_000,
map: (a) => ({ id: a.id, text: a.title, importance: a.severity * 20, url: a.link }),
}));
// Any EventSource endpoint.
herald.source(sseSource({ url: '/events', events: ['alert'] }));
// The three.ws rail (below).
herald.source(railSource());
The rail
The rail is what lets something with no browser (a deploy script, a cron, a CI job, an AI agent) reach the browser a person is actually looking at.
Announce
POST /api/herald/announce
Authorization: Bearer sk_live_... # or a signed-in session cookie
Content-Type: application/json
{ "text": "Deploy is green", "importance": 80, "url": "/dashboard", "from": "CI" }
{
"queued": true,
"id": "6a293426-8f48-4254-bc14-cef9ada17680",
"expires_in": 300,
"announcement": { "id": "...", "text": "Deploy is green", "importance": 80, "tone": "alert", "at": 1787888380209 }
}
| Field | Type | Notes |
|---|---|---|
text (or message) |
string, 1-280 | Required. Written as speech, not as a log line. |
from |
string, max 60 | Spoken as attribution. |
importance |
int 0-100 | Default 70. The receiving client applies its own floor. |
url |
string | Same-origin path or absolute http(s). Anything else is dropped. |
tone |
neutral | alert | celebrate | error |
Default alert. |
emote |
string | wave, dance, punch, backflip. |
key |
string, max 120 | Dedupe key: two announcements sharing one are said once. |
meta |
object | Returned untouched to the client's callbacks. |
202 means queued for a live surface, not heard by a human: nothing on the
server can promise the second thing.
Addressing is the security model. An announcement always goes to the
authenticated caller's own sessions. There is no recipient field, so a key
cannot be used to interrupt anybody else, and the worst a leaked key can do is
annoy the person who leaked it. Keys are minted at
/dashboard/developers with the
herald:announce scope and revoked in the same place.
Listen
GET /api/herald/stream # session cookie only
Server-sent events: open once, then one announce per queued line, with a
ping every 15 seconds. The queue is drained (not broadcast), so a message is
said by exactly one open tab. An undelivered line expires in about five minutes:
this is a live channel, and the durable record is the notification bell.
Rate limits: 60 announces per minute per account, 60 stream connections per five minutes.
The CLI
export THREE_WS_API_KEY=sk_live_... # herald:announce scope
herald say "Migration finished" --from db --url https://three.ws/dashboard
herald watch --from CI -- npm test
herald ping
watch runs the command with its stdio attached, keeps its exit code, times it,
and announces the outcome (CI passed in 2m, CI failed (exit 1) after 47s).
Failures arrive at importance 95 so they cut through quiet hours; successes at
60 so they do not. Because the exit code is preserved, it drops into a pipeline
unchanged:
herald watch -- npm test && npm run deploy
From an AI agent
claude mcp add herald -e THREE_WS_API_KEY=sk_live_... -- npx -y @three-ws/herald-mcp
Three tools: announce (say one line), announce_result (report a finished
task, with the urgency chosen from the outcome), and check_rail (prove the key
works without interrupting anyone). Full reference in
packages/herald-mcp.
This is the piece that changes how a long agent run feels: the agent works for twenty minutes while you do something else, and then your own avatar walks on and tells you it is done.
Accessibility
The avatar is the point, but it is never the requirement.
- No WebGL, an iframe, a route that already owns the corner: the card presenter
takes over. It is theme-aware, honours
prefers-reduced-motionandprefers-color-scheme, is dismissible withEscape, and has real focus rings. - Both presenters deliver into an
aria-liveregion, so assistive technology announces the line at the same moment everyone else hears it. - Audio is opt-in and gesture-gated.
voice: 'auto'speaks only once the browser has seen a real interaction; refused audio degrades to the text that is already on screen.
Where the code is
| Piece | Path |
|---|---|
| Rules engine (pure, unit-tested) | herald-sdk/src/rules.js |
| Runtime | herald-sdk/src/index.js |
| Presenters | herald-sdk/src/presenters/ |
| Sources | herald-sdk/src/sources/index.js |
| CLI | herald-sdk/bin/herald.mjs |
| Rail | api/herald/announce.js, api/herald/stream.js, api/_lib/herald.js |
| CDN entry | src/herald-embed.js served at /herald.js |
| Playground | pages/herald.html, src/herald-page.js |
| MCP server | packages/herald-mcp/ |
| Tests | tests/herald-rules.test.js, tests/herald-runtime.test.js, tests/herald-rail.test.js, tests/herald-announce-endpoint.test.js |
Related
- Notifications: the bell, the inbox API, and the per-category avatar channel that uses this on three.ws itself.
- walk-sdk: the 3D body, and
control.announce(), the primitive the avatar presenter delivers through. - The developer platform: API keys, scopes, and usage.