main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-notifications description: >- How Hydrogen on Linux reaches the user outside the window: desktop notifications through adom-cli notify (the Hydrogen window raises them on the desktop's notification server), the title-bar bell, and the in-app /ui/toast. Use when asked to notify me, send a desktop notification, tell me when it's done, or show a toast.

Hydrogen on Linux: Notifications

The bell in the Title Bar

The bell right of the pencil (Annotate) and left of the avatar is the one-time switch for browser notifications from the editor itself: code-server and the extensions inside it raise Notification events (a task finished, an extension wants attention) and the webview only shows them once the user has granted permission. The bell with a dot means "not asked yet": one click asks, and a confirmation notification proves it works. Once granted the bell disappears; a crossed bell means permission was denied. This is separate from the desktop notifications below, which the AI fires through adom-cli notify and which need no bell.

When the user is not looking at Hydrogen (a long build is running, you finished a job, or you are blocked and need them), fire a notification instead of printing into a panel nobody is watching.

Desktop notification: adom-cli notify

adom-cli notify --title "Build complete" "hd build finished, exit 0"
adom-cli notify --title "Need your OK" --require-interaction "Approve the schematic change?"
adom-cli notify --title "Export" --tag export-progress "42 of 100 parts"   # same tag replaces

The workspace's adom-cli sends it to Hydrogen (POST .../current/notification on Hydrogen's proxy), Hydrogen's window raises it with the page Notifications API, and WebKitGTK hands it to the desktop's notification server (GNOME's banner and message tray, Cinnamon's, any freedesktop notification daemon). Flags: --icon (an image or data URL, not an iconify name), --tag, --require-interaction (stays until dismissed), --silent, --no-focus-on-click (by default a click brings Hydrogen forward).

Read the answer, it is the real outcome: shown, permission_required, denied, unsupported, or no_browser (Hydrogen's window is not connected). Hydrogen grants every permission request its pages make, so permission_required should be rare; if it appears, ask the user to click the bell in the Title Bar once.

Do Not Disturb on the desktop hides banners; the notification still lands in the message tray.

In-app toast — POST /ui/toast (inside the Hydrogen window)

The desktop notification above reaches the user outside the window. For a lightweight message inside the Hydrogen window — the same toast UI the app uses for its own success/error messages — fire a control-API toast:

# via the control API (or adom-cli hydrogen api, or the API Explorer "Try it")
POST /ui/toast { "message": "Build finished ✅", "type": "success", "duration": 5000 }
Field Notes
message Required. The toast text.
type info (default) / success / warning / error — sets icon + color.
duration ms before auto-dismiss (default 5000). 0 = persistent until the user dismisses.
groupId + detail Optional: coalesce related toasts into one expandable group.

It emits the hd-toast Tauri event, which the main window renders via the global toastStore (bottom-stacked toasts). Use a desktop notification when the user may be away from Hydrogen; use /ui/toast for an in-window status cue while they work in it.

From the workspace shell:

curl -s -X POST "$(cat ~/.adom/hydrogen-control-url)/ui/toast" -H 'Content-Type: application/json' \
  -d '{"message":"Build finished","type":"success","duration":5000}'

Adom Bridge's notify_user

adom-bridge notify_user reaches this machine while Adom Bridge runs here (Hydrogen installs and starts it when a Linux build is published for the user's account; it shows notifications through notify-send). It also reaches the user's OTHER machines through the mesh: adom-bridge --target <machine> notify_user '{"title":"...","body":"..."}', for example to pop a toast on their Windows PC.

When you (the AI) should notify proactively

  • Long-job completion: a build, a batch, a render, a deploy finished. Fire a desktop notification so the user can wander off and get pulled back.
  • You need the user: an approval, a decision, a credential. Add --require-interaction.
  • Hands-free / driving — pair a notification with audio (TTS) so the user gets both a glance-able toast and the spoken answer.

One notification per meaningful event, no spam. Check the result field before telling the user you notified them.

  • hydrogen-captions: on-screen captions inside Hydrogen
  • hydrogen-adom-bridge: what Adom Bridge is and how to reach other machines