Skip to content
Miloš Vasić

// tier: vasic-util-secondary · order 27

Herald activelicense: UNVERIFIED

GoShellClaude Code (LLM intent inference)Messenger channel adaptersDocs ChainHelix Constitution submodule

Source

Herald — event fan-out to channels Channels (fan-out) intent ladder: command → LLM inference → clarify Governance + docs Event source tracker / doc change Herald Go · intent inference Slack adapter Telegram adapter Email adapter …messenger adapters HelixConstitution governance Docs Chain doc corpus
// architecture

Every alert reaches the right destination — no command syntax required.

An event ingestion and multi-channel notification fan-out system. Herald reliably routes system events to the right destinations across messenger channels, and lets subscribers speak plain natural language — resolving intent through a command fast-path, LLM inference, and a clarify-and-ask fallback.

Herald ingests system events and reliably fans them out to multiple notification channels so every alert reaches the right place. Subscribers interact in plain natural language; Herald infers intent via a three-tier discipline (command fast-path → LLM intent inference → clarify fallback).

Herald is the notification backbone that guarantees a system event actually lands where a human can act on it — the unglamorous but mission-critical layer where most homegrown alerting quietly fails. It ingests events and fans them out reliably across multiple notification channels, closing off the familiar failure modes where an alert is dropped, mis-routed to a dead channel, or buried under noise until it's too late to matter. But reliable delivery is only half the story; the other half is what happens when a human wants to respond. Here Herald refuses the usual bargain where users must memorize a rigid command syntax to interact with an alerting bot. Subscribers simply write in plain natural language, and Herald resolves what they meant through a deliberate three-tier discipline: a fast-path that recognizes explicit commands instantly, then LLM-based intent inference (via Claude Code) for free-form messages, and finally a clarify fallback that replies, tags, and asks a question when intent is genuinely ambiguous. That "recognize → infer → clarify" ladder is the whole design philosophy in miniature — the common case stays instant and deterministic, the flexible case is handled by a model, and the uncertain case is never resolved by a blind guess that fires the wrong action. Herald also models participation and attribution: an operator-username env var (HERALD_<CHANNEL>_OPERATOR_USERNAME) and a participant/attribution contract drive created_by/assigned_to fields and notification @-tagging, so it is clear who did what and who is being notified. Governance-wise, Herald inherits the Helix Constitution as a co-located submodule and follows its rules, and it is an early production consumer of Docs Chain — its full 66-document Markdown→HTML/PDF/DOCX corpus is wired through Docs Chain exec: transforms and verifies clean. Herald is primarily Shell/Go tooling with layered specifications (V1→V2→V3→V4 supersession) and per-channel operator setup guides for messengers and LLM/agent dispatchers.

The itch we had to scratch

Alerts fail quietly — sent to the wrong channel, dropped, or requiring rigid command syntax users won't remember. Herald was built to guarantee reliable fan-out and to let people respond in natural language, so notifications are both dependable and effortless to act on.

Why it matters

It fuses two things that are usually bought as separate products — dependable multi-channel event routing and a natural-language interface — into one system where operators simply talk and the software works out what they mean. The clarify fallback is the detail that makes it trustworthy in production: an alerting system that would rather ask than misfire is one you can actually let touch real state.

Ideas worth stealing

Where it got hard, and how we won

The engineering stack