DEV Community: Bryan Clark

Push SignalK alarms to your phone with a zero-dependency relay

Bryan Clark — Tue, 23 Jun 2026 20:25:37 +0000

SignalK knows when something is wrong. It raises alarms into its notifications.* tree with a clear severity ladder:

nominal < normal < alert < warn < alarm < emergency

A low-battery condition shows up as a warn; a man-overboard lands at notifications.mob with state emergency. The data is right there, structured and timestamped:

{
  "notifications": {
    "mob": {
      "value": {
        "state": "emergency",
        "method": ["visual", "sound"],
        "message": "Man overboard"
      },
      "timestamp": "2026-06-01T19:30:00Z"
    }
  }
}

The problem: nothing pushes those alarms to your phone when you're not standing in front of the chartplotter. If you're below, ashore, or asleep, the alarm fires into the void. We wanted one dependable thing — a SignalK notification turning into a push on a phone — and we wanted it on a safety path, which raises the bar.

This is the broke → tried → fixed of getting SignalK push notifications to your phone. The punchline: a one-way SignalK→ntfy relay needs zero npm dependencies, so we built signalk-ntfy-relay.

What we evaluated (and why each fell short)

Option 1: the classic Pushover relay — stale

The most-referenced community answer to "SignalK notification to phone" is a relay plugin that forwards notifications to a push service. The canonical one is signalk-pushover-notification-relay, targeting Pushover.

The architecture is right — subscribe to notifications, POST to a push service. But the receipts are bad:

$ npm view signalk-pushover-notification-relay
signalk-pushover-notification-relay@1.0.0 | ISC | deps: none
published over a year ago

$ # repo: last pushed 2022 — roughly four years stale

When we checked, the repo hadn't moved since 2022 and pushover.net was unresponsive. The plugin is fine; the sink is the problem. You do not want to hang a safety-relevant alert on a paid, closed service that's unresponsive when you test it, behind a plugin nobody's touched in four years.

That sent us looking for a better sink.

The better sink: ntfy

ntfy is the right target. It's open-source, free, self-hostable, actively maintained, and has real iOS and Android apps. Most importantly, its publish API is just an HTTP POST — title, priority, and tags all ride in headers:

curl \
  -H "Title: Low battery" \
  -H "Priority: 4" \
  -H "Tags: rotating_light" \
  -H "Authorization: Bearer tk_yourtoken" \
  -d "House bank below 30%" \
  https://ntfy.sh/your-topic

Priority is 1 (min) through 5 (max). Tags is a comma-separated list of emoji shortcodes that render as icons on the notification. That's the entire contract. No SDK, no handshake — a POST with headers. For a man-overboard you'd send:

curl -H "Title: MOB" -H "Priority: 5" -H "Tags: sos" \
  -d "Man overboard" https://ntfy.sh/your-topic

Self-hostable, free, maintained, and a one-line publish API. That's the sink. Now: who relays SignalK into it?

Option 2: the existing ntfy plugin — an early POC with the wrong scope

There's already a plugin: signalk-ntfy (Enand-lab/signalk-ntfy). Verify it yourself — here's what we found:

$ npm view signalk-ntfy
signalk-ntfy@0.0.4 | Apache-2.0 | deps: 2
dependencies:
  node-fetch: ^2.7.0
  ws: ^8.16.0
published 2 months ago

$ # GitHub: ~9 commits, single author, 0 stars / 0 forks

This is an early proof-of-concept: 0.0.4, one author, single-digit commits, effectively no adoption. That alone is reason to be careful on a safety path — but the more interesting issue is scope.

signalk-ntfy is bidirectional. Its headline feature is interactive ntfy buttons whose responses get published back into SignalK. That's a neat idea, and it's exactly why it pulls in two runtime dependencies:

ws — a WebSocket client to listen for button-press responses coming back from ntfy.
node-fetch — to POST to ntfy.

For a one-way safety relay, the bidirectional half is dead weight, and both dependencies exist only to serve it. Worse, for our purposes the POC is missing the things a relay actually needs:

edge-triggering — notify on a state change, not repeatedly while a condition persists;
severity filtering — a configurable floor so alert-level chatter doesn't page you;
severity → ntfy priority/tags mapping — so an emergency arrives as priority 5 with an SOS icon;
position enrichment — where was the boat when this fired;
tests.

So the choice was: adopt an immature 0.0.x and bolt the relay essentials onto a bidirectional architecture we don't want — or build a focused relay.

Option 3: a generic SignalK→MQTT gateway — wrong shape

We also considered routing notifications through a generic SignalK→MQTT bridge and pushing from there. Wrong shape for a phone push: it speaks a foreign topic scheme, carries no notion of ntfy priority or tags, and pushes the severity→presentation mapping problem somewhere else instead of solving it. A relay should own the SignalK-notification → phone-push semantics end to end.

The decision: a focused, zero-dependency relay

Here's the key insight that made the whole thing easy: a one-way SignalK→ntfy relay needs no npm dependencies at all. Both of the existing plugin's dependencies fall away once you drop the bidirectional feature.

No ws. A SignalK plugin runs in-process inside the SignalK server, so it reads notifications directly through the plugin API — no external WebSocket client. You subscribe to the notifications.* subtree:

module.exports = function (app) {
  const plugin = { id: 'signalk-ntfy-relay', name: 'SignalK ntfy relay' };

  plugin.start = function (options) {
    app.subscriptionmanager.subscribe(
      {
        context: 'vessels.self',
        subscribe: [{ path: 'notifications.*', policy: 'instant' }]
      },
      [],                                   // unsubscribes array
      (err) => app.error(err),
      (delta) => handleDelta(app, options, delta)
    );
  };

  return plugin;
};

The ws dependency in the existing plugin exists only to hear button responses come back from ntfy. A relay never listens, so it's gone.

No node-fetch. Node ships an HTTPS client. The entire ntfy POST is the standard library:

const https = require('node:https');

function postToNtfy({ server, topic, token, title, priority, tags, body }) {
  const url = new URL(topic, server);          // e.g. https://ntfy.sh/your-topic
  const headers = {
    'Title': title,
    'Priority': String(priority),              // 1..5
    'Tags': tags.join(',')                     // emoji shortcodes
  };
  if (token) headers['Authorization'] = `Bearer ${token}`;

  const req = https.request(url, { method: 'POST', headers });
  req.on('error', (err) => app.error(`ntfy post failed: ${err.message}`));
  req.end(body);
}

That's it. node-fetch was only ever a polyfill for fetch/HTTP — and on a modern Node runtime you don't need it for a single POST.

Edge-triggering: notify on change, not on repeat

The relay essential the POC lacks. SignalK can re-emit a notification delta while a condition holds; you do not want a buzz every few seconds for a battery that's still low. Keep an in-memory Map of the last state seen per path and only fire on transitions:

const lastState = new Map();   // path -> last notification state

function handleDelta(app, options, delta) {
  for (const update of delta.updates ?? []) {
    for (const { path, value } of update.values ?? []) {
      const state = value?.state ?? 'normal';   // nominal|normal|alert|warn|alarm|emergency
      if (lastState.get(path) === state) continue;   // no change — skip
      lastState.set(path, state);

      if (severityRank(state) < severityRank(options.minSeverity)) continue;
      relay(app, options, path, value, state, update.timestamp);
    }
  }
}

One transition, one push. A condition that clears (back to normal/nominal) is itself a transition — so you can send a "cleared" notification too, instead of leaving a stale alarm on the phone.

Severity → priority + tags

The mapping that turns a SignalK state into something ntfy renders meaningfully — loud icons for the loud states:

const RANK = {
  nominal: 0, normal: 0, alert: 1, warn: 2, alarm: 3, emergency: 4
};
const severityRank = (s) => RANK[s] ?? 0;

// state -> { ntfy priority (1..5), tags (emoji shortcodes) }
const NTFY = {
  emergency: { priority: 5, tags: ['sos'] },
  alarm:     { priority: 4, tags: ['rotating_light'] },
  warn:      { priority: 3, tags: ['warning'] },
  alert:     { priority: 2, tags: ['information_source'] },
  cleared:   { priority: 1, tags: ['white_check_mark'] }   // back to normal/nominal
};

An emergency (man-overboard) lands as priority 5 with an SOS icon; a clear comes through as a quiet priority-1 check mark.

Position enrichment

When something fires, where were we? If the vessel has a fix, append a position line to the push body:

function withPosition(app, body) {
  const pos = app.getSelfPath('navigation.position')?.value;
  if (!pos) return body;
  const ns = pos.latitude >= 0 ? 'N' : 'S';
  const ew = pos.longitude >= 0 ? 'E' : 'W';
  return `${body}\n${Math.abs(pos.latitude).toFixed(4)} ${ns}, ` +
         `${Math.abs(pos.longitude).toFixed(4)} ${ew}`;
}

Self-hosted server + token

ntfy is self-hostable, so the server URL and an optional bearer token are config, defaulting to the public instance:

{
  "server": "https://ntfy.sh",
  "topic": "your-topic",
  "token": "tk_optional_for_self_hosted_or_private_topics",
  "minSeverity": "warn"
}

Why zero-dependency is the point, not a flex

It would be easy to read "zero dependencies" as a vanity metric. On a safety path it isn't:

Smaller supply-chain and audit surface. Every dependency is code you didn't write running on the path between "alarm fired" and "phone buzzed." For something safety-relevant, the right number of transitive packages to audit is as close to zero as you can get. With node:https and the in-process plugin API, there's nothing to audit but the plugin itself.
Nothing to vendor or break on upgrade. node-fetch v2 vs v3 (CommonJS vs ESM), ws majors — these are exactly the upgrades that silently break a plugin you forgot you were running. No deps, no upgrade treadmill.
Readable end to end. You can sit down and read the whole relay in one pass and convince yourself it does what it says. That property is worth more on an alarm path than any feature.

The contrast is the whole argument: the existing plugin's two dependencies aren't waste — they earn their keep serving the bidirectional button feature. A one-way relay simply doesn't have that feature, so it doesn't pay that cost.

What we did not do, honestly

Use signalk-ntfy as-is. An immature 0.0.x with no adoption, on a safety-relevant path, missing edge-triggering / severity filtering / tests. No.
Contribute the changes upstream. Tempting, but its bidirectional architecture and goals genuinely differ from a one-way relay. Bending a focused relay onto a button-response design — or pushing a from-scratch rewrite into someone else's POC — serves nobody. A separately-publishable, single-purpose relay is cleaner and more reusable for the next person searching "signalk ntfy."
Build a generic SignalK→MQTT gateway. Wrong shape (covered above): foreign topic scheme, no severity/priority semantics, just relocates the mapping problem.

Tests

A safety relay gets tests, and node:test ships with Node — so even the test layer adds no dependency:

const { test } = require('node:test');
const assert = require('node:assert');

test('edge-triggering fires once per transition', () => {
  const seen = [];
  const opts = { minSeverity: 'warn', topic: 't', server: 'https://ntfy.sh' };
  const send = (path, v, s) => seen.push(s);

  step(opts, 'notifications.x', 'warn', send);   // fire
  step(opts, 'notifications.x', 'warn', send);   // repeat — skip
  step(opts, 'notifications.x', 'alarm', send);  // change — fire

  assert.deepStrictEqual(seen, ['warn', 'alarm']);
});

test('emergency maps to priority 5 / sos', () => {
  assert.deepStrictEqual(NTFY.emergency, { priority: 5, tags: ['sos'] });
});

Close

This came out of building the AI and notification plumbing for an all-electric sailing charter — where "the battery alarm fired" needs to reach a phone, not just the chartplotter, and the path it travels has to be auditable end to end. signalk-ntfy-relay is MIT-licensed and zero-dependency — on npm as signalk-ntfy-relay and on GitHub. Install it from the SignalK app store (search "ntfy") or with npm i signalk-ntfy-relay. If you've been searching for SignalK push notifications to your phone — a SignalK notification relay that turns a SignalK alarm into a phone push — that's what it's for.

SEO and GEO on TanStack Start: prerender to static

Bryan Clark — Tue, 23 Jun 2026 20:25:33 +0000

We moved the Sailing Naturali apex site off Squarespace and onto a code-owned TanStack Start app on Vercel. The point wasn't to save the $28/month — it was to stop editing the site through a GUI and start editing it through a git repo: content as files, every change a PR, every PR a Vercel preview, merge to ship. The repo is public: github.com/sailingnaturali/web.

The interesting part wasn't the migration. It was discovering that SEO and GEO are the same problem wearing two hats, that TanStack Start ships with the one default that breaks both, and that fixing it is a single config block. This is the broke → tried → fixed of getting search engines and answer engines to actually see a TanStack Start site — plus the verification gotchas that made a correct build look broken.

Problem

The classic SEO checklist (title, meta description, canonical, Open Graph, structured data) and the newer GEO checklist (be legible to GPTBot, PerplexityBot, ClaudeBot, Google AI Overviews) read like two different jobs. They are not. They share one spine:

A bot fetches a URL and has to understand the page from the bytes it gets back — without running your JavaScript. Googlebot can render JS, but defers it and penalizes you for the round trip. The answer-engine crawlers largely don't render at all. So whether you're chasing a blue link or a cited sentence in an AI answer, the win condition is identical: return clean, fully-rendered HTML with good structured data on the first request.

TanStack Start, by default, does the opposite. It client-renders. Build the site, open the production HTML, and the body is an empty shell:

<!-- .output/public/index.html — client-rendered default -->
<body>
  <div id="root"></div>
  <script type="module" src="/assets/entry-client-xxxx.js"></script>
</body>

That's what every bot sees: an empty <div id="root"> and a script tag. Googlebot queues it for deferred rendering; GPTBot and PerplexityBot see nothing worth quoting. You can have perfect meta tags and it doesn't matter, because the content the page is about never made it into the response.

Diagnosis

The fix is not "add more meta tags." It's "stop shipping an empty root div." Once the rendered text and the structured data are in the static HTML, both checklists collapse into one:

Classic SEO wants <title>, <meta name="description">, <link rel="canonical">, OG/Twitter cards, and Schema.org JSON-LD — all in the first response.
GEO wants the same first-response HTML to be content-complete (the prose is actually there) plus a machine-readable map of the site so answer engines know what you are and which pages matter.

Both are downstream of one decision: prerender to static at build time. Everything else — JSON-LD, sitemap, llms.txt — layers on top of prerendered HTML and is nearly free once the prerender works. So prerendering is the highest-leverage move, and it's where we started.

What we tried (and why it failed)

Attempt 1 — meta tags first, prerender "later"

The tempting order is to nail the head (title/description/canonical/OG) first because it's the visible SEO surface, and treat prerendering as a perf optimization for later. We wired up a pageHead() helper and shipped it on a client-rendered build.

Result: the meta tags were correct, and the page body was still empty to a bot.

# build, then look at what a crawler actually receives
$ pnpm build
$ grep -a "all-electric" .output/public/index.html
# (no output — the page's actual content isn't in the HTML)

Lesson: meta tags describe a page whose content isn't there. For Googlebot it's a deferred-render penalty; for a non-rendering answer-engine crawler it's invisible. Ordering matters — prerender is the prerequisite, not the polish.

Attempt 2 — enable prerender, but verify with plain `grep`

We turned on prerendering (config below), rebuilt, and checked the output. On macOS:

$ grep "all-electric" .output/public/index.html
Binary file .output/public/index.html matches

…and worse, a phrase grep came back empty:

$ grep "can't" .output/public/index.html
# (no output)

That looked like the prerender had failed — empty matches and a "binary file" warning. It hadn't. Two separate verification traps, both of which make a correct build look broken (diagnosed in the gotchas below). We nearly reverted a working config because the check lied.

Attempt 3 — local install fails on a build-script gate

With prerendering on, a fresh local install started failing where CI on Vercel didn't:

 ERR_PNPM_IGNORED_BUILDS  Ignored build scripts: esbuild.
Run "pnpm approve-builds" to pick which dependencies should be allowed
to run scripts, or set them in the dependenciesMeta field of package.json.

The reflex is to re-add the old pnpm.onlyBuiltDependencies array to package.json — and on a current pnpm that field is ignored there, so nothing changes. The approval setting has moved out of package.json and into pnpm-workspace.yaml (fix below). This one didn't bite on Vercel — only locally — which is exactly the kind of environment skew that eats an afternoon.

The fix

1. Prerender to static (the whole ballgame)

In vite.config.ts, enable prerendering on the TanStack Start plugin and add the nitro plugin for the Vercel target:

// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { nitro } from 'nitro/vite'

export default defineConfig({
  plugins: [
    tanstackStart({
      prerender: {
        enabled: true,
        autoSubfolderIndex: true,        // /about -> /about/index.html
        autoStaticPathsDiscovery: true,  // find routes automatically
        crawlLinks: true,                // follow <a> tags and prerender them too
        concurrency: 14,
      },
    }),
    nitro(),
  ],
})

Now the build emits real HTML, content and all. Verify it (correctly — see gotchas):

$ pnpm build
$ grep -a "all-electric" .output/public/index.html
... an all-electric charter catamaran ...   # rendered text, not an empty root div

That's the entire premise of the post in one config block. Everything below is layering.

2. JSON-LD via route `head.scripts` — it really does prerender

You do not need to hand-render a <script type="application/ld+json"> in your component body. TanStack Start's route head.scripts emits inline JSON-LD straight into the prerendered <head>:

// src/routes/index.tsx (abridged) — the home route carries the site-level JSON-LD
import { pageHead, organizationJsonLd, websiteJsonLd } from '../lib/seo'

export const Route = createFileRoute('/')({
  head: () => ({
    ...pageHead(home),
    scripts: [
      { type: 'application/ld+json', children: JSON.stringify(organizationJsonLd()) },
      { type: 'application/ld+json', children: JSON.stringify(websiteJsonLd()) },
    ],
  }),
})

Verified in the static output — two inline JSON-LD blocks (Organization + WebSite) land in the <head> of .output/public/index.html:

$ grep -a -o 'application/ld+json' .output/public/index.html | wc -l
       2

If a future version regresses this, the fallback is a script tag rendered in the component body:

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify(organizationJsonLd()) }}
/>

3. A single source of truth, and build-time SEO assets

Two small modules keep this maintainable so adding a page doesn't mean editing five files:

src/lib/site.ts — siteConfig plus a pages registry. Adding a page is one row; the sitemap and llms.txt follow from it.
src/lib/seo.ts — pageHead() (title/description/canonical/OG/Twitter) and organizationJsonLd() / websiteJsonLd().
src/lib/seo-assets.ts — pure builder functions for sitemap.xml, robots.txt, and llms.txt.

The assets are generated at build time, before vite build, by a small script run through tsx:

// package.json
{
  "scripts": {
    "build": "tsx scripts/generate-seo-assets.mjs && vite build"
  }
}

Because the builders are pure functions over the pages registry, the sitemap and llms.txt can't drift from the actual site — they're derived from the same data the router uses.

4. `llms.txt` — the GEO-specific lever

llms.txt (llmstxt.org, Jeremy Howard's spec) is a plain-Markdown map of the site for answer engines: a one-line description, then the core pages with short summaries. It's the GEO analogue of robots.txt/sitemap.xml — instead of telling crawlers where they may go, it tells models what you are and which pages matter:

# Sailing Naturali

> A tech exec is using AI leverage to build a premium all-electric sailing
> charter in the Pacific Northwest — the kind of business AI can't deliver.

## Pages

- [Sailing Naturali — an all-electric charter, built with AI](https://sailingnaturali.com): ...

(That's the live /llms.txt today — one page, because the site launched as one page. As routes land in the pages registry, the file grows with them for free.)

Honest caveat: adoption is uneven and Google has publicly said llms.txt is not required. We ship it anyway because it's a build-time-generated byproduct of the pages registry — near-zero cost, plausible upside, trivially removable. Treat it as future-proofing, not a silver bullet.

5. The pnpm build-script gate

Move the build-script approval out of package.json (where pnpm 11 silently ignores it — that's the deprecation warning you keep seeing) and into pnpm-workspace.yaml. On pnpm 11 the mechanism is an allowBuilds map of booleans:

# pnpm-workspace.yaml
allowBuilds:
  esbuild: true
  lightningcss: true

After this, pnpm install runs the postinstall (esbuild fetches its platform binary) and pnpm build works with no --config.verify-deps-before-run=false escape hatch. (On older pnpm 10 the equivalent was an onlyBuiltDependencies array in the same file — check your pnpm major; the durable point is the setting lives in pnpm-workspace.yaml, not package.json.)

6. The cutover — keep your TLS cert and your canonical

DNS lives on Cloudflare. The trap is the orange cloud: if Cloudflare proxies the records, Vercel can't complete the ACME challenge to provision its own TLS cert. Set the relevant records to DNS-only (grey cloud) so Vercel owns TLS end to end:

# Cloudflare DNS — all DNS-only (grey cloud)
A      @      76.76.21.21            ; apex -> Vercel (use the IP Vercel shows you)
CNAME  www    cname.vercel-dns.com   ; www -> 307 redirect to apex

(76.76.21.21 is Vercel's standard apex IP, but it assigns from an Anycast pool — use whatever value the Vercel domain dashboard hands you rather than copying this one.)

Two things that make the cutover boring instead of scary:

Canonical points at the apex from day one. og:url and <link rel="canonical"> are built from siteConfig.url (the apex), not the request host — so even on the *.vercel.app preview, search sees the apex as canonical. The moment DNS flips, the right canonical is already in the HTML; no duplicate-content window.
Email and verification survive the host swap. MX, SPF, DKIM, and the DNS-based google-site-verification TXT record are independent of where the website is hosted. Leave them in place and they ride through the cutover untouched.

Why it matters / gotchas

The two verification traps from Attempt 2 are worth their own section, because they make a correct build look like a failure and will send you reverting good code:

Gotcha #1 — macOS/BSD grep reports a correct build as "binary." Nitro emits index.html as a single long UTF-8 line packed with em-dashes and inline scripts. BSD grep (the macOS default) sniffs that as binary and prints Binary file ... matches instead of the line — or, with some flags, silently nothing. Force text mode:

$ grep -a "all-electric" .output/public/index.html   # -a = treat as text

Gotcha #2 — React HTML-escapes apostrophes, so your grep misses real content. React renders can't as can't in the static HTML. A naive grep "can't" (or grep "can.t") finds nothing and you conclude the prerender dropped the content. It didn't — grep an apostrophe-free phrase:

$ grep -a "all-electric charter" .output/public/index.html   # no apostrophe, matches

Both of these bite hardest precisely when the build is correct, which is the worst time to get a false negative.

The deeper lesson is the spine itself: don't model SEO and GEO as two backlogs. They're one — get clean, content-complete, well-structured HTML into the first response — and on TanStack Start that reduces to flipping prerendering on and then layering cheap, build-time-generated assets on top. The framework gives you the hard parts (typed head, JSON-LD in head.scripts, Nitro prerendering, link crawling); you supply a single source of truth so the derived assets can't drift. Worth reading alongside this: the official TanStack Start SEO and LLMO guides, which land on the same conclusion from the framework side.

Close

This is the apex marketing site for an all-electric charter catamaran we're building in the open — but the site itself is just a TanStack Start app, and the SEO/GEO module is reusable on any TanStack Start project. It's all in the public repo: github.com/sailingnaturali/web.

Fix LLM formatting in the tool layer, not the prompt

Bryan Clark — Tue, 23 Jun 2026 17:57:58 +0000

If you point an LLM agent at an MCP server and then route its replies through text-to-speech, you will eventually hear it say something like:

"Your position is forty-eight point seven six degrees north, one two three point zero four degrees west, and state of charge is zero point six eight."

That is a raw latitude/longitude pair and a 0–1 fraction being read aloud verbatim. The instinct is to fix it in the prompt — "always speak the battery as a percentage," "format position as degrees north and west." That instinct is a trap. This is the broke → tried → fixed of getting clean spoken output, and the punchline is: format in the tool response, not in the prompt.

This is a design post, not a single-bug writeup, but it maps to the same arc — a wrong behaviour, a dead-end that looks right, and a fix that actually holds.

Problem

The boat agents here run on a local LLM with a Home Assistant voice front-end, backed by a set of MCP servers. The agent calls a tool, gets JSON back, composes a reply, and TTS speaks it. The trouble starts with what's in that JSON.

SignalK stores everything in SI units, so a wind-speed read comes back as bare metres-per-second:

{ "path": "environment.wind.speedApparent", "value": 8.5, "timestamp": "2026-05-18T00:00:00Z" }

A battery state-of-charge comes back as a 0–1 fraction:

{ "capacity": { "stateOfCharge": { "value": 0.68 } } }

A position comes back as a coordinate dict:

{ "value": { "latitude": 48.7601, "longitude": -123.0410 } }

A timestamp comes back as ISO 8601 UTC:

{ "timestamp": "2026-06-01T19:30:00Z" }

Feed any of those to an LLM and tell it to talk, and you get raw values spoken aloud:

"Eight point five."                                # the raw m/s, not knots
"State of charge zero point six eight."            # wrong — should be 68%
"Forty-eight point seven six zero one degrees      # unspeakable
 north, negative one two three point zero four
 one zero degrees..."
"Twenty twenty-six dash zero six dash zero one     # reads the ISO string
 tee nineteen thirty zero zero zed."

The model is not malfunctioning. It is doing exactly what an LLM does: it sees a number it recognizes as a coordinate or a fraction, and it renders it however it feels like this turn.

Diagnosis

Here is the part that took a couple of cycles to internalize: the model reformats raw data it can see, regardless of your instructions, because it "knows" what that data is. It has seen a billion latitudes. It knows 0.68 near a key called stateOfCharge is a fraction. It knows an ISO timestamp. So it will "helpfully" expand, convert, or mangle the raw field — and which way it mangles depends on the model, the temperature, and the phase of the moon.

That means a prompt rule isn't a fix, it's a suggestion the model is free to ignore the moment the raw value is still in front of it. You can't reliably instruct the model not to reformat data it can plainly read. The only reliable lever is the data itself: don't put the raw value where the model will narrate it.

What we tried (and why it failed)

The dead-end: fix it in the prompt

The obvious first move is to add formatting rules to the agent's system prompt:

# system prompt — formatting rules (the dead-end)
When you report battery state of charge, always say it as a
percentage (e.g. "68 percent"), never as a decimal.
When you report position, say it as degrees north and degrees
west, rounded to two decimals (e.g. "48.76 north, 123.04 west").
When you report a time, say the local time, never the UTC
timestamp.
Speak wind speed in knots.

On the model and temperature you tested it on, this mostly works. Ship it, and within a day TTS says:

"State of charge is zero point six eight."

…because on this turn the model decided the decimal was fine. Tighten the rule, add an example, and now it works again — until you swap the local model for a different size, or the cloud model ships a new version, and the behaviour drifts back. Every fix is per-model and per-temperature.

It also doesn't compose. Each new field is a new rule:

# ...and it keeps growing
Depth is in meters; say it in feet if under 10 meters...
Heading is degrees true; say "degrees" not "degrees true"...
Distance to waypoint is in meters; say nautical miles if over 1000...

The prompt becomes a pile of unit-conversion rules, the model still leaks one of them on any given turn, and you're playing whack-a-mole against a non-deterministic narrator. The root cause — the raw value is right there in the tool result — is untouched. This is a structural dead-end, not a tuning problem.

The fix

Move the formatting into the tool response. Three techniques, in order of preference. All three are from our public MCP servers, so the real tool and field names below are fine to copy.

1. Pre-format a `display` field

Give the model a string that is already correct to read aloud, and let the raw value ride alongside for any code that needs to compute on it.

read_sensor (signalk-mcp) — the SI value rides alongside a pre-converted display:

{
  "path": "environment.wind.speedApparent",
  "value": 8.5,
  "display": "16.5 knots",
  "unit": "knots",
  "timestamp": "2026-05-18T00:00:00Z"
}

battery_state (signalk-mcp) — display is a full spoken summary, with the units spelled out so TTS reads them naturally:

{
  "bank": "house",
  "soc_fraction": 0.68,
  "voltage": 12.84,
  "current": -8.2,
  "display": "68 percent, 12.8 volts, 8.2 amps discharging",
  "timestamp": "2026-05-14T18:00:00Z"
}

mark_moment (logbook-mcp):

{
  "id": 7,
  "entry_display": "Entry 7",
  "text": "Beautiful sunset off Discovery Island",
  "timestamp": "2026-06-01T19:30:00Z",
  "position": { "longitude": -123.04, "latitude": 48.42 },
  "position_display": "48.4 North, 123.0 West"
}

The model reaches for the obvious field to speak, and the obvious field is now the right one. This is the highest-leverage move and should be the default for anything that has a "natural" spoken form.

2. Remove the raw field entirely

A display field still leaves the raw value sitting in the JSON, and a model can still decide to narrate soc_fraction instead of display. When there is no good reason to return the raw value at all, don't.

get_local_time (signalk-mcp) returns no utc field — only the already-local, already-formatted time and the timezone it resolved to. There is no UTC string or ISO timestamp for the model to read aloud:

{
  "iana_timezone": "America/Vancouver",
  "display": "19:30"
}

(display is HH:MM in 24-hour local time; the tool resolves the timezone from the vessel's GPS position and falls back to "UTC" with no fix.)

Position is the instructive exception. The same principle suggests dropping the raw lat/lon — but here it collides with a real need: agents calling read_sensor("navigation.position") need actual coordinates for programmatic use (computing a distance, feeding the next tool), not just a string to speak. So read_sensor deliberately keeps the raw dict in value and leans on technique 1 (a good display) for the spoken form:

{
  "path": "navigation.position",
  "value": { "latitude": 48.76, "longitude": -123.05 },
  "display": "48.7600 North, 123.0500 West",
  "unit": "°",
  "timestamp": "2026-05-18T00:00:00Z"
}

That is the trade-off technique 2 forces you to make explicit: remove the raw field when nothing downstream needs it; keep it — and accept you're back to relying on technique 1 — when something does. get_local_time has no consumer for a UTC string, so it drops it outright and unspeakable output becomes impossible. Position has real consumers for the coordinates, so it keeps them and accepts the residual risk that a model could expand the dict into "negative one two three point zero five degrees." Knowing which case you're in is the real decision — not reflexively stripping every raw field.

3. Name keys so they don't leak

Key names leak into speech too — a model will sometimes narrate the field name, and a key that reads like a sentence fragment ("state of charge…", "timezone…") invites it. Name any key whose value isn't meant to be spoken so it reads as an opaque identifier, not prose. The two raw fields in these servers are named exactly this way:

soc_fraction    # not "state_of_charge": "soc fraction" won't get read as prose,
                # and it signals "this is a 0–1 number, not the thing to speak"
iana_timezone   # not "timezone": "America/Vancouver" is a machine value, and the
                # name says so — the spoken value lives in `display`

The naming also encodes intent for the next person reading the schema: soc_fraction says this is a 0–1 number, the percentage is in display. The spoken form always lives in a display/*_display field; the raw fields carry names that read as machine values. If a key's name would be spoken naturally, that's the smell — rename it or drop it.

Why it matters / the one place a prompt rule is fine

The principle generalizes past voice and past marine data: anywhere an LLM tool result feeds generated output, formatting belongs in the tool response, because that's the only layer that's deterministic. The prompt is advisory; the tool result is data. Put the contract in the data.

There is exactly one place where a prompt instruction is the right tool — and it's worth calling out so you don't over-rotate into "never touch the prompt":

When the agent composes a confirmation sentence and reformats a value it already holds in context. Say mark_moment already gives back position_display: "48.4 North, 123.0 West", but the agent is writing a full confirmation like "Marked. We're at forty-eight point four north, one twenty-three west." That is sentence structure, not a unit conversion — the model is arranging a value it legitimately has, into prose. A single, one-line format instruction tied to that specific tool response is fine there:

# acceptable prompt rule — sentence structure, not unit conversion
After mark_moment, confirm using position_display verbatim,
phrased as "<position_display>".

The line to hold: a prompt rule that says how to arrange values into a sentence is fine. A prompt rule that says convert this unit / expand this fraction / reformat this timestamp is the dead-end — that always belongs in the tool response. If you find yourself writing a conversion rule in the prompt, that's the signal to go fix the tool instead.

A couple of nearby traps:

A display field alone is not airtight. As long as the raw field is still in the payload (technique 1), a model can still read it. Remove the raw field (technique 2) whenever nothing downstream needs it — that's the only way to make unspeakable output impossible rather than merely discouraged. When something genuinely needs the raw value (position's coordinates), you're knowingly back to relying on display; that's a deliberate trade-off, not an oversight.
Test on more than one model. The whole reason prompt rules fail is cross-model drift. Your tool-layer fix should be verified the same way — swap the local model, bump the cloud model version, confirm the JSON still speaks correctly. If it's in the tool response, it will; that's the point.

Close

This came out of building an AI ops layer for an all-electric charter catamaran — a local LLM, SignalK, and a stack of MCP servers behind a Home Assistant voice front-end, where "what's our position" has to come back as something a human can actually hear. The servers the examples above are pulled from are open source: github.com/sailingnaturali (signalk-mcp, logbook-mcp).

launchd's minimal PATH breaks MCP servers: uv command not found

Bryan Clark — Tue, 23 Jun 2026 17:57:54 +0000

A stdio MCP server is just a subprocess. Your agent runtime runs something like
uv run my-mcp-server, talks to it over stdin/stdout, and exposes its tools to
the model. That works perfectly when you launch the agent from your terminal.
Move the same agent under a launchd service — a LaunchAgent, a daily job, a
bridge that restarts on crash — and the MCP tools vanish. No crash, no stack
trace, no log line. The model just says it doesn't have the tools. This is the
broke → tried → fixed of why.

Problem

We run a local AI agent (Hermes) that loads several MCP servers over stdio. Each
one is declared in config with a command: that gets exec'd as a subprocess.
The natural way to write it — the way that works at the prompt — is to name the
launcher and let PATH resolve it:

# agent config — mcp_servers
mcp_servers:
  signalk:
    command: uv          # <-- resolved via PATH
    args: ["run", "signalk-mcp-server"]
  weather:
    command: uv
    args: ["run", "weather-mcp-server"]

Run the agent by hand and every tool is live. Then we wired the agent into a
launchd-managed pipeline — a daily job kicked off by a LaunchAgent — and the
agent came up fine, answered normally, but reported it had no SignalK or
weather tools. Asked for a sensor reading, the model says some version of:

I don't have a tool available to read that.

That's the whole symptom. The agent process is healthy. The conversation works.
There is no error in the agent log, no traceback, no "spawn failed" — the MCP
servers simply aren't there. And the tell that sends everyone down the wrong path:
run the exact same agent from an interactive shell and it works every time.

Diagnosis

launchd does not give your process the environment from your shell. It gives it a
minimal PATH:

/usr/bin:/bin:/usr/sbin:/sbin

No ~/.local/bin. No /usr/local/bin. No /opt/homebrew/bin. None of the
PATH edits from your .zshrc / .zprofile, because launchd doesn't source a
login shell. So when launchd execs the agent and the agent tries to spawn
command: uv, the lookup fails:

$ which uv
/Users/you/.local/bin/uv      # in your shell
                              # ...not on launchd's PATH

uv (installed by the standalone installer) lives in ~/.local/bin. So does the
agent binary itself (hermes), and plenty of other modern CLIs. Under launchd,
uv is simply not found.

The reason this is so disorienting is where the failure lands. The agent
launches the MCP server as a child process and treats "couldn't start" as
"server not available" — exactly the same state as a server you didn't configure.
A stdio MCP transport that can't exec its command doesn't throw up into your
chat loop; it just never produces a tool list. So the model is told nothing is
there, and faithfully reports nothing is there. The root cause (ENOENT on uv)
is three layers down and never surfaces.

Two facts combine into the trap:

launchd's PATH is minimal and doesn't include ~/.local/bin — this is by design (launchd.info, and Apple's launchd.plist EnvironmentVariables key is the supported way to change it).
A failed MCP subprocess spawn degrades silently to "tool unavailable" — no different from a server you never configured.

What we tried (and why it failed)

Because the symptom is "MCP tools missing," every instinct points at the MCP
layer. All of these were dead ends.

Attempt 1 — restart the MCP server / restart the agent

The reflex: it's a stale or crashed server, bounce it.

# restart the agent's MCP gateway, reload config, retry
hermes gateway restart

Result: no change. The tools are still missing under launchd, and — the
confusing part — they were never actually crashing. There was nothing to
restart, because nothing had started. Restarting a process that fails to spawn
just fails to spawn again, identically and silently.

Attempt 2 — assume the config / transport is wrong

Next suspicion: a bad server entry, wrong transport, a typo in the command. So we
re-read the config, double-checked the MCP server URLs and args, tried an
HTTP/SSE server instead of stdio to see if stdio was the problem:

  signalk:
    command: uv
    args: ["run", "signalk-mcp-server"]   # looks correct...

Result: the config is correct. Run the agent in a terminal with this exact
config and all tools enumerate. The transport is fine; stdio is fine; the args
are fine. Every direct test of the configuration passes — because every direct
test runs in your shell, with your PATH.

Attempt 3 — chase a phantom server outage

If the agent says the server's unavailable, maybe the server is down. So we went
looking for a crashed backend, a port conflict, a wedged process. There was
nothing to find: the standalone MCP smoke test connects and lists its tools just
fine, because it, too, runs in an interactive shell:

$ hermes mcp test signalk      # run by hand → works
✓ connected, 7 tools

Every isolated test passed. That's the signature of this bug, and it's worth
saying plainly:

Interactive shell: works. Under launchd: fails. Same machine, same config,
same binary. When you see that split, stop debugging the application and
start debugging the environment — specifically PATH.

We were debugging MCP for an hour. The bug was never in MCP.

The fix

Don't rely on PATH resolution for anything a launchd-managed process spawns.
Use absolute paths in every command: entry:

# agent config — mcp_servers, launchd-safe
mcp_servers:
  signalk:
    command: /Users/you/.local/bin/uv     # absolute — no PATH lookup
    args: ["run", "signalk-mcp-server"]
  weather:
    command: /Users/you/.local/bin/uv
    args: ["run", "weather-mcp-server"]

One line on why: an absolute path skips PATH lookup entirely, so launchd's
stripped environment can't break it. (Find the real path with which uv in your
shell — typically ~/.local/bin/uv for the standalone installer,
/opt/homebrew/bin/uv under Homebrew on Apple Silicon.)

Reproduce it before you "fix" it. This one-liner runs any command under
launchd's exact minimal PATH, so you can confirm the failure (and confirm the
fix) without deploying through launchd:

/usr/bin/env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin uv --version
# uv: command not found      <-- reproduces the launchd failure

/usr/bin/env -i PATH=/usr/bin:/bin:/usr/sbin:/sbin /Users/you/.local/bin/uv --version
# uv 0.x.y                   <-- absolute path works

If you'd rather keep command: uv readable, the alternative is to hand launchd a
richer PATH via the plist EnvironmentVariables key (this affects the whole job,
not just one command):

<key>EnvironmentVariables</key>
<dict>
  <key>PATH</key>
  <string>/Users/you/.local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>

Both work. We chose absolute paths in the command entries because the failure
mode they prevent is silent, and an absolute path is self-documenting: it can't
drift when someone edits their shell profile.

The robust version: resolve the path yourself and fail loudly

For subprocesses you spawn in your own code (a generator, a build step, a
bridge), hardcoding an absolute path is brittle across machines. Better: resolve
via which, fall back to the known install dir, and raise a clear error if the
binary genuinely isn't there — so a missing tool is loud, not a mystery:

import shutil
from pathlib import Path

def resolve_cli(name: str) -> str:
    """Find a CLI on PATH, fall back to ~/.local/bin, else fail loudly."""
    exe = shutil.which(name)
    if exe:
        return exe
    fallback = Path(f"~/.local/bin/{name}").expanduser()
    if fallback.exists():
        return str(fallback)
    raise FileNotFoundError(
        f"{name} not found on PATH or ~/.local/bin — install it "
        f"(e.g. `uv tool install {name}`) or add its dir to PATH."
    )

# subprocess.run([resolve_cli("vessel-knowledge"), "zones", ...])

The ~/.local/bin fallback covers launchd's stripped PATH; the explicit
FileNotFoundError turns the next occurrence of this bug from a silent
"tools unavailable" into a one-line error that names the missing binary.

Why it matters / gotchas

This is not specific to MCP, uv, or even macOS. Any process spawned by
launchd, cron, or a systemd unit that resets PATH (User= services often
do) gets a stripped environment. Anything that worked because your shell profile
put a directory on PATH — uv, pipx shims, node via a version manager,
brew-installed tools — can vanish the moment it's launched by a scheduler
instead of by you. The MCP server is just the messenger.
The real lesson is the silent-failure shape, not the PATH fact. Plenty of
people know launchd has a minimal PATH. What costs the hours is that a failed
subprocess spawn surfaces as "feature not available" with no error, two or
three layers up from the cause. When a launchd-run thing behaves as if a whole
capability is missing, suspect a child process that couldn't exec before you
suspect the capability.
"Works in my shell" is not a test of a launchd job. Your interactive shell
has a PATH a scheduler never will. Always test scheduled work under the
scheduler's environment — the /usr/bin/env -i PATH=... one-liner above is the
cheapest way to do it.
Fail loudly when a required binary is missing. The fix that prevents the
recurrence isn't the absolute path; it's the FileNotFoundError. A tool that
silently degrades when a dependency is absent will cost someone this exact hour
again. Make "binary not found" a loud, specific error.

Close

This came out of building an AI ops layer for an all-electric charter catamaran —
a local LLM, SignalK, and a stack of MCP servers, with a daily briefing kicked
off by a launchd job. "Why does the agent lose its tools only when the scheduler
starts it" turned out to be a one-word answer: PATH. The MCP servers behind it
are open source — github.com/sailingnaturali/signalk-mcp
is a representative stdio server, and the rest live at
github.com/sailingnaturali.

No audio from the Home Assistant Nabu puck: use assist_satellite.announce

Bryan Clark — Tue, 23 Jun 2026 17:41:31 +0000

You wire up a local voice pipeline on a Home Assistant Voice (Nabu) puck, fire a tts.speak at it from an automation, and nothing comes out. The pipeline runs. Home Assistant reports the TTS call succeeded. There is no speech. Worse, when you poke at it in Developer Tools, the media_player entity flips to playing exactly like you'd expect — so it looks like it's working, and you spend an hour staring at a service call that does nothing audible.

The root cause: the puck isn't a plain media player. It's an assist_satellite entity, and that changes how you have to route TTS. Get past that and there are two follow-on traps — announcing into a busy satellite, and a silently-crashed Piper add-on that masquerades as the original "no speech" symptom. Here's the full broke → tried → fixed.

Problem

You push text to the puck and it never speaks. Search terms for the person hitting this right now: Home Assistant Nabu voice no audio, Voice PE tts.speak no sound, assist_satellite no speech media_player.

The obvious service call — speak some text to the puck's media player:

service: tts.speak
target:
  entity_id: tts.piper          # your TTS engine entity
data:
  media_player_entity_id: media_player.home_voice   # the puck
  message: "Depth is 4.2 metres under the keel, Captain."

In Developer Tools → States, media_player.home_voice dutifully flips to playing and shows the media metadata. The speaker stays silent. This is the trap: the state change is real, the audio is not.

Diagnosis

The puck is not a plain media player. The Home Assistant Voice puck runs ESPHome, and the ESPHome integration exposes it as an assist_satellite entity — an entity "which represents a voice satellite, with its state following the underlying Assist pipeline." Both the esphome and voip integrations were transitioned to AssistSatelliteEntity. This is true the moment the device is adopted; it has nothing to do with installing the Whisper add-on. (Whisper is just one way to give the pipeline local STT — Speech-to-Phrase and Home Assistant Cloud are the other two. None of them is what creates the satellite entity.) If you only realized the puck was a satellite around the time you set up local STT, that's coincidence, not cause.

The satellite owns its own audio path, driven by its configured pipeline. tts.speak with media_player_entity_id targets the generic media-player surface instead. In our setup, that surface is effectively vestigial on the satellite — HA updates the media_player entity state to playing, but no audio comes out, because nothing routed the speech through the satellite's announcement path. No error, no log line, just silence. (We're not the only ones who've watched tts.speak to a satellite go quiet — the community "still can't make tts.speak work" threads are full of it — but the exact behavior depends on your device and TTS engine, so treat this as our-setup observation, not a documented contract.)

The action that does route through the satellite's audio path is assist_satellite.announce, which converts the message to a media id "using the text-to-speech system of the satellite's configured pipeline."

What we tried (and why it failed)

Dead-end 1: `tts.speak` to the media_player entity

The call above. Result: media_player.home_voice shows playing, attributes populate, zero audio. No exception in the logs. This is the most expensive dead-end precisely because it half-works — the state machine lies to you.

Dead-end 2: immediate ack + async response (two announces)

Once you switch to assist_satellite.announce, the next instinct is conversational polish: speak an instant "One moment" so the user knows they were heard, then speak the real answer when the slow work (a tide lookup, an LLM round-trip) finishes:

# DON'T — two announces fired without waiting for the first to finish
- service: assist_satellite.announce
  target:
    entity_id: assist_satellite.home_voice
  data:
    message: "One moment, Captain."
- service: assist_satellite.announce      # fires while #1 is still going
  target:
    entity_id: assist_satellite.home_voice
  data:
    message: "{{ answer }}"

The trouble is timing. The docs say async_announce "should only return when the announcement is finished playing on the device," and that the satellite stays in responding until something calls tts_response_finished to bring it back to idle. So the second announce lands while the satellite is still responding from the first — and in our testing that's where it goes wrong: the second announce gets dropped or the satellite wedges.

How much of this is "documented bug" vs. "our setup" is worth being precise about, because the upstream picture is messier than it first looks:

There is a report of an assist satellite stuck in the "responding" state (core #142363) — but it's about the satellite failing to return to idle after a normal conversation, and it was closed as not planned, so don't read it as a confirmed fix or as proof that announcing-into-responding deadlocks. It just establishes that the responding state can hang.
There's a community thread, "executing two assist_satellite.announce in a script fails," but read it carefully: the failure was specific to a script called from a voice intent, and the diagnosed cause was mixing announce with set_conversation_response on the same device — not two announces colliding in general. The same two-announce script ran fine from an automation or Developer Tools. So it's a real gotcha, but a narrower one than "two announces always conflict."

Bottom line: the reliable rule that fixed it for us is one announce, fired only when the satellite is idle — see the fix. We treat "announcing into responding wedges the satellite" as our-setup behavior, consistent with the docs' state machine but not something upstream has labeled a bug.

Dead-end 3: everything's correct and it's still silent

You've got assist_satellite.announce, a single call, fired on idle — and after some unrelated restart it goes mute again. Same signature as the very first problem: pre-announce chime, then no speech. You re-check your service call. It's fine.

It's not your call. The Piper add-on had crashed and never came back. TTS has no engine, so the message never gets synthesized and nothing speaks. Piper crashing on TTS calls is not just us: Piper: Crash after any TTS call (addons #3379) reports exactly this — ConnectionResetError then a FileNotFoundError on an empty audio path, i.e. the synthesis never produced a file. With no watchdog, a crashed Piper stays down and there's no obvious symptom pointing at it.

Note on the chime: assist_satellite.announce plays a pre-announce chime that is itself a media id, and the Voice puck also has its own on-device wake/feedback sounds. We saw the device still making a sound while speech was dead, which is what made this so confusing — but whether a given chime survives a dead Piper depends on where that chime comes from. Don't over-read it; the reliable tell is below.

The fix

Three things, all small:

1. Use assist_satellite.announce, targeting the satellite entity:

service: assist_satellite.announce
target:
  entity_id: assist_satellite.home_voice   # your puck's assist_satellite entity
data:
  message: "Depth is 4.2 metres under the keel, Captain."

Substitute your own entity ID — it's machine-local. Find it in Developer Tools → States by filtering on assist_satellite..

2. One announce, on idle only. Drop the immediate-ack pattern. Fire a single announce with the final response, and only when the satellite is idle — never while it's responding. If you need a "thinking" cue, do it without a second announce (a UI/light cue, or let the pipeline's own response carry it).

3. Turn on the Piper add-on watchdog. Settings → Add-ons → Piper → enable Watchdog. (This is our mitigation, not something the upstream issue prescribes.) Without it, a crashed Piper stays down and takes all TTS with it until you notice.

And the one diagnostic that saves the most time: when speech goes mute, check the Piper add-on status before you touch your automation. Speech depends on Piper; if Piper is down, no announce and no tts.speak will ever produce audio, no matter how correct the call is. The Piper add-on log (ConnectionResetError, FileNotFoundError on an empty path) is the giveaway. Don't trust a chime as proof the audio path is healthy — see the gotcha below.

Why it matters / gotchas

State changes are not proof of audio. tts.speak to a satellite's media_player entity updating to playing tells you nothing about whether sound came out. On assist_satellite devices, trust your ears (or the satellite's own state), not the media_player entity.
The puck is a satellite from the start. The ESPHome integration exposes the Voice puck as an assist_satellite the moment you adopt it — local STT (Whisper, Speech-to-Phrase, or Cloud) has nothing to do with it. So target assist_satellite.announce from day one; a tts.speak-to-media_player automation may never have made sound on this device, you just didn't notice until you needed it to talk.
Treat responding as busy. Per the docs, a satellite stays in responding until tts_response_finished returns it to idle. Fire your announce only on idle. Better still, where you can, let the normal conversation pipeline return the speech response — it flows back through the satellite without you hand-rolling an announce at all. (And note responding can itself hang — core #142363 — independent of anything you do.)
Don't trust a chime. Something on the device may keep chiming while speech is stone dead, which is exactly what sends you debugging your automation instead of the TTS engine. Whether a particular chime survives a dead Piper depends on where it's generated, so don't reason from it — check Piper.

Close

This came out of building a local voice front-end for the boat-agent stack on Sailing Naturali — an all-electric charter catamaran where the helm talks to a local LLM through a Home Assistant Voice puck. The agent and MCP tooling are open source under github.com/sailingnaturali; the voice front-end notes live alongside them.

Route all Home Assistant voice to a custom agent with a wildcard sentence

Bryan Clark — Tue, 23 Jun 2026 17:41:28 +0000

If you want every voice command to go to your own conversation agent — a local LLM, an MCP-backed assistant, whatever — instead of Home Assistant's built-in intents, the obvious approach is a catch-all wildcard. On HA 2026.5+ that obvious approach returns an HTTP 500 with MissingListError, and the queries that do parse get silently hijacked by built-in intents. This is the broke → tried → fixed of getting it working.

Problem

The goal: route all voice through to a custom agent (in our case, a local Hermes 3 model behind an MQTT bridge). The symptom when you try it the obvious way — a conversation trigger with a bare wildcard:

# automations.yaml — the obvious catch-all
- alias: "Route voice query to my agent"
  triggers:
    - trigger: conversation
      command:
        - "{text}"
  actions:
    - action: mqtt.publish
      data:
        topic: my/agent/ask
        payload: '{"text": "{{ trigger.slots.text }}"}'

Speak anything and the conversation API returns:

HTTP 500 Internal Server Error
hassil.errors.MissingListError: Missing slot list {text}

And the requests that don't 500 get worse: queries you'd expect to fall through to your agent get answered by a built-in intent instead. "When is the next low tide" comes back as:

I'm sorry, no device is playing.

That's MediaPlayerNext matching on "next." Other built-ins join in: HassGetState grabs "when is {name}", HassTurnOn grabs "turn on {name}", HassFanSetSpeed grabs "[set] {name} [to] {speed}". Your custom routing never gets a look in.

Diagnosis

Two separate things are happening, and it's easy to conflate them.

1. MissingListError is how hassil 3.x resolves {slot}. Home Assistant's sentence matcher is hassil. In the 3.x line (3.0.0 was a March 2025 rewrite; 3.5.0 shipped Dec 2025, and a 3.x is what current HA ships — we hit this on HA 2026.5), a {slot} reference inside a sentence template is resolved as a named list lookup — it expects a list called slot to exist under lists:. If no such list is registered, parsing raises MissingListError, which surfaces as an HTTP 500 on the /api/conversation/process endpoint. A bare {text} is not a wildcard — it's a reference to a list named text that you never defined. (If you're coming from an older setup where a bare trigger slot seemed to "just work," that's the change to be aware of; declare the wildcard explicitly now.)

2. The hijacking is intent ordering. Even once you stop 500-ing, HA's built-in intents are in the match set. Several of them are broad enough to swallow general English — MediaPlayerNext matches "next [anything]", HassGetState matches "when is …", and so on. Whoever matches first wins, and the built-ins were matching first.

So the fix has to do two jobs at once: register a real wildcard so the slot resolves, and get our intent to match ahead of the built-ins.

What we tried (and why it failed)

Attempt 1 — automation `conversation` trigger with a bare wildcard

# automations.yaml
- alias: "Route voice query to my agent"
  triggers:
    - trigger: conversation
      command:
        - "{text}"          # <-- treated as list lookup, not wildcard
  actions:
    - action: mqtt.publish
      data:
        topic: my/agent/ask
        payload: '{"text": "{{ trigger.slots.text }}"}'

Result:

hassil.errors.MissingListError: Missing slot list {text}
→ HTTP 500 on the conversation API

This is a structural dead-end, not a typo. The conversation trigger accepts sentence templates, but it gives you nowhere to declare a lists: block — there is no wildcard: true knob on an automation trigger. So any {slot} you put in a trigger command is forced to be a named-list lookup, and you have no way to register that list. You cannot build a true catch-all out of an automation trigger on hassil 3.x. (Renaming {text} to {slot} changes nothing — same error, different list name.)

Attempt 2 — narrow the greedy built-ins instead

If general queries are being eaten by MediaPlayerNext and friends, maybe just redefine those built-ins to be less greedy and let everything else fall through:

# custom_sentences/en/naturali.yaml
language: "en"
intents:
  MediaPlayerNext:
    data:
      - sentences:
          - "(skip|next) (song|track)"
          - "play next (song|track)"
  MediaPlayerPause:
    data:
      - sentences:
          - "(pause|stop) [the] (music|playback)"
  # ...and the rest of the media intents, narrowed

This did stop "when is the next low tide" from hitting MediaPlayerNext — narrowing the sentences works. But it's whack-a-mole: every broad built-in (HassGetState, HassTurnOn, HassFanSetSpeed, …) is a separate intent you'd have to find and re-scope, and a future HA release can add or widen one and silently start swallowing your queries again. It also still depends on Attempt 1's trigger to actually catch the fall-through — which 500s. Narrowing the built-ins treats the symptom; it doesn't give you a catch-all.

The fix

Move the catch-all out of the automation trigger and into a custom sentence with a real wildcard list, then handle the intent with intent_script.

custom_sentences/en/naturali.yaml:

language: "en"
intents:
  NaturaliQuery:
    data:
      - sentences:
          - "{text}"
lists:
  text:
    wildcard: true

configuration.yaml:

intent_script:
  NaturaliQuery:
    speech:
      text: "One moment, Captain."
    action:
      - action: mqtt.publish
        data:
          topic: naturali/intents/ask
          payload: '{"text": "{{ text }}"}'

Two things make this work where the trigger couldn't:

lists: text: wildcard: true registers text as a WildcardSlotList, so {text} matches arbitrary speech instead of resolving to a missing named list. No more MissingListError. Custom sentences are the only place you can declare this — which is exactly what the automation trigger lacked.
Custom sentences load before built-in HA intents (in our testing on HA 2026.5). So NaturaliQuery is matched first and intercepts everything — including the HassGetState / HassTurnOn / HassFanSetSpeed / MediaPlayerNext matches that were hijacking sailing queries. That ordering is the whole reason this fixes the hijacking without touching a single built-in.

intent_script (rather than an automation) handles the matched intent: it speaks the acknowledgement back through the normal voice pipeline and publishes the query text downstream. Note the slot is referenced as {{ text }} in intent_script — not {{ trigger.slots.text }}; there's no trigger object here.

Reload custom sentences (conversation.reload) for the sentence change; intent_script lives in configuration.yaml, so that part needs a full HA restart to take effect.

Why it matters / gotchas

The fix hinges on the thing that's also the trap: custom sentences load before built-ins, so a {text} wildcard intent swallows the entire grammar. That's the feature here — we want everything to go to the agent. But if you only want some sentences routed to your agent and the rest handled by HA natively, a bare {text} wildcard is a sledgehammer: it will intercept "turn on the lights" too, and your built-in device control stops working. For partial routing, scope the wildcard sentence (a required prefix word, a leading keyword) so it doesn't match plain device commands.

Other things worth knowing:

MissingListError → HTTP 500 is generic. Any undeclared {slot} in a custom sentence or trigger produces it, not just wildcards. If you see it, look for a {slot} with no matching lists: entry.
intent_script over an automation action for the response. Handling the response in intent_script keeps the speech flowing back through the conversation pipeline. If your TTS satellite is the kind that deadlocks when you call its announce service while it's mid-response (some assist-satellite setups do), routing the reply through intent_script.speech sidesteps that entirely — you never issue a competing announce call.
Don't bother narrowing the built-ins. Once the wildcard custom sentence is in front, it matches first and the built-ins never get the query. The narrowing work from Attempt 2 becomes dead code.

Close

This came out of building an AI ops layer for an all-electric charter catamaran — local LLM, SignalK, MCP servers, voice on a Home Assistant front-end — where "when is the next low tide" needs to reach the navigation agent, not a media player. The MCP servers that sit behind this voice routing are open source: github.com/sailingnaturali.

DEV Community: Bryan Clark

Push SignalK alarms to your phone with a zero-dependency relay

What we evaluated (and why each fell short)

Option 1: the classic Pushover relay — stale

The better sink: ntfy

Option 2: the existing ntfy plugin — an early POC with the wrong scope

Option 3: a generic SignalK→MQTT gateway — wrong shape

The decision: a focused, zero-dependency relay

Edge-triggering: notify on change, not on repeat

Severity → priority + tags

Position enrichment

Self-hosted server + token

Why zero-dependency is the point, not a flex

What we did not do, honestly

Tests

Close

SEO and GEO on TanStack Start: prerender to static

Problem

Diagnosis

What we tried (and why it failed)

Attempt 1 — meta tags first, prerender "later"

Attempt 2 — enable prerender, but verify with plain grep

Attempt 3 — local install fails on a build-script gate

The fix

1. Prerender to static (the whole ballgame)

2. JSON-LD via route head.scripts — it really does prerender

3. A single source of truth, and build-time SEO assets

4. llms.txt — the GEO-specific lever

5. The pnpm build-script gate

6. The cutover — keep your TLS cert and your canonical

Why it matters / gotchas

Close

Fix LLM formatting in the tool layer, not the prompt

Problem

Diagnosis

What we tried (and why it failed)

The dead-end: fix it in the prompt

The fix

1. Pre-format a display field

2. Remove the raw field entirely

3. Name keys so they don't leak

Why it matters / the one place a prompt rule is fine

Close

launchd's minimal PATH breaks MCP servers: uv command not found

Problem

Diagnosis

What we tried (and why it failed)

Attempt 1 — restart the MCP server / restart the agent

Attempt 2 — assume the config / transport is wrong

Attempt 3 — chase a phantom server outage

The fix

The robust version: resolve the path yourself and fail loudly

Why it matters / gotchas

Close

No audio from the Home Assistant Nabu puck: use assist_satellite.announce

Problem

Diagnosis

What we tried (and why it failed)

Dead-end 1: tts.speak to the media_player entity

Dead-end 2: immediate ack + async response (two announces)

Dead-end 3: everything's correct and it's still silent

The fix

Why it matters / gotchas

Close

Route all Home Assistant voice to a custom agent with a wildcard sentence

Problem

Diagnosis

What we tried (and why it failed)

Attempt 1 — automation conversation trigger with a bare wildcard

Attempt 2 — narrow the greedy built-ins instead

The fix

Why it matters / gotchas

Close

Attempt 2 — enable prerender, but verify with plain `grep`

2. JSON-LD via route `head.scripts` — it really does prerender

4. `llms.txt` — the GEO-specific lever

1. Pre-format a `display` field

Dead-end 1: `tts.speak` to the media_player entity

Attempt 1 — automation `conversation` trigger with a bare wildcard