Adom Hydrogen (Linux)
Public Made by Adomby adom
The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.
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.
Related skills
- hydrogen-captions: on-screen captions inside Hydrogen
- hydrogen-adom-bridge: what Adom Bridge is and how to reach other machines
---
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`
```bash
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:
```bash
# 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:
```bash
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.
## Related skills
- hydrogen-captions: on-screen captions inside Hydrogen
- hydrogen-adom-bridge: what Adom Bridge is and how to reach other machines