Skip to content

feat(better-alerts): macOS notifications, and say what the agent asked or did - #42

Open
munza wants to merge 2 commits into
mainfrom
better-alerts-macos
Open

munza wants to merge 2 commits into
mainfrom
better-alerts-macos

Conversation

@munza

@munza munza commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Summary

Better Alerts now works on macOS, and every alert says what the agent asked or did.

sequenceDiagram
    participant Mod as Better Alerts (main.js)
    participant App as HerdrAlerts.app
    participant MacOS as macOS
    participant Herdr
    Mod->>Mod: hc read <agent> → words.js
    Mod->>App: open -g -n … --args post title tab message target
    App->>MacOS: UNUserNotificationCenter (Herdr's name + icon)
    App-->>App: quits
    MacOS->>App: click relaunches it
    App->>Herdr: herdr-app do agent.focus <target>, then bring Herdr forward
Loading
 better-alerts/
+├── helper/            # main.swift, Info.plist, build.sh → bin/HerdrAlerts.app (ad-hoc signed)
 ├── mods/better-alerts/
 │   ├── main.js        # macOS: open HerdrAlerts.app, else osascript; Linux: notify-send as before
+│   └── words.js       # title, tab line, question / reply from the screen (pure, tested)
 └── sync.sh            # keeps the installed bin/

The wording:

-Claude Code needs you
-lantern-app / Fix the login form
+Claude Code / lantern-app - NEEDS YOU
+Fix the login form                                   ← macOS: subtitle
+Do you want to make this edit to login.js?           ← macOS: body
+Fix the login form · Do you want to make this edit…  ← Linux: body, one line
  • The tab line is left out when it's named like the space or is only a number.
  • The message is the lowest line ending in ? (needs you), or how the last reply began (done): from Claude Code's ⏺ or Codex's •, with the prompt, status bar and timing lines skipped. It's cut to 140 characters.
  • On macOS, alerts from one agent stack together in Notification Centre. On Linux, the tab and message are joined with ·, because GNOME shows a banner's body on one line and turns a newline into a plain space. The body is escaped for markup daemons.
  • If macOS refuses the app, it posts through osascript instead and says to allow Herdr in System Settings → Notifications.

Evidence

  • Before: on macOS, window().platform !== "linux" → no timer, no alerts.
    After: checked by hand on macOS 27. The helper was built by build.sh and posted Claude Code / herdr-app - DONE / Fix the login form / the reply. The banner had Herdr's icon, and a click from another app showed the agent with Herdr in front. Note: this was the real helper and the real words posted by hand, not the installed mod reacting to a status change.
  • Preview: preview.png is now GNOME Shell 43's own banners, rendered headless from the mod's exact notify-send call with the new wording. Its bullets say "macOS and Linux" and "Shows its question or reply". That render is also how I found the newline problem: GNOME showed "Fix the login form Do you want…" as one run-on line.
  • Tests: node --test */tests/*.test.cjs site/tests/*.cjs: 415 pass, 0 fail. New Better Alerts tests:
    macOS posts via open -g -n HerdrAlerts.app, osascript until it's built
    body = tab + question/reply, with & < > escaped
    title = "<program> / <space> - NEEDS YOU|DONE"; tab left out when redundant
    question: lowest "?" line without box sides; reply: from ⏺/• past chrome, cut at a word
    unreadable screen → message left out
    
  • herdr-app check mods/better-alerts passes, helper/build.sh builds a signed app, and the site builds.
  • Not checked: Linux on a real desktop since the wording change (tests only).

Merge Danger

Door: two-way

Nothing is migrated. Reverting brings back the old wording and Linux-only behaviour. A helper that was already built just stays unused in bin/.

Blast Radius: Alerts

  • Linux users see new titles. The body now carries the agent's question or reply, and an hc read runs per alert.
  • macOS users start getting alerts. The first one may ask to allow "Herdr" notifications.
  • The alerts.blocked and alerts.done settings are unchanged.

🤖 Generated with Claude Code

munza and others added 2 commits November 19, 2026 14:39
…d or did

On macOS, Better Alerts now posts through HerdrAlerts.app, a small Swift
app that helper/build.sh compiles and signs on the person's Mac. Its
notifications carry Herdr's name and icon, and a click (even after the app
quit) shows the agent and brings Herdr forward. Until it's built, or when
macOS refuses it, alerts go through osascript.

Every notification now reads "<program> / <space> - NEEDS YOU|DONE", then
the tab, then the agent's question or how its last reply began, read from
its screen with hc read. Linux escapes the body for markup daemons.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… a new preview

GNOME shows a banner's body on one line, with a newline as a plain space,
so "Fix the login form Do you want…" read as one sentence. The preview is
now GNOME's own banners with the new wording, and its bullets say macOS and
Linux, and that the alert shows the question or reply.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant