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-ui description: >- Hydrogen's interface (menus, dialogs, panels, profile menu, setup panel, tray menu) and how to drive it from the workspace via the UI command bus (GET /ui/actions, POST /ui/invoke) instead of clicking. Use when asked to open or close a Hydrogen dialog or menu, where a UI element is, or how to eval in Hydrogen's page on Linux.
Hydrogen — UI Reference
Hydrogen on Linux is a Tauri app on WebKitGTK. The UI is the same as everywhere; what differs is how you reach into the page (no Chrome DevTools Protocol, see "Eval" below).
Window Layout
Hydrogen's window has these regions (top to bottom, left to right):
Title Bar (frameless, 0.1.251+)
Hydrogen is a FRAMELESS window: the nav bar IS the title bar (no separate OS chrome).
- Left: Adom logo (the Adom menu button), then the lightbulb (sample-prompts menu, moved here 0.1.265) — drag anywhere else in the bar to move the window
- Right: CPU/RAM badges, the Annotate pencil, the profile avatar menu, then the window controls (minimize, maximize, close).
- The window has no system frame: it resizes from its edges.
- All title-bar controls share one interaction family: soft white hover wash, teal press, steady teal wash while their menu is open
Tab Bar
- VS Code tab — the main code editor (iframe to code-server)
- Webview tab — wiki/app content panel
- Additional tabs for bridges, sensors, etc.
Main Content Area
- Left pane: Usually VS Code iframe
- Right pane: Usually webview (wiki, shotlog, etc.)
- Panes are split and resizable
Moving tabs between panes (drag-to-split, 1.0.140+)
Drag any tab and hover another pane: teal drop zones light up (Split Left / Right / Top / Bottom, Swap, or the tab bar to add). This works over EVERY pane type, webviews included (a glass layer covers iframes during the drag so they cannot swallow the pointer), and exactly ONE zone pill shows at a time. Releasing on a zone performs the move; Escape abandons the drag and everything returns to exactly how it was. Right-clicking a tab offers the same splits as menu items (a one-tab pane asks what to put in the new half via Add Panel).
Setup Panel (bottom)
- Collapsible panel showing the setup steps
- See
hydrogen-setupskill for details
Menus
Adom Menu (top-left logo dropdown)
The main menu, opened by clicking the Adom logo at the top-left. Items are grouped into labelled sections (in order, top to bottom):
(top, unlabelled) — "Go to Dashboard" was REMOVED (0.1.252, John 2026-07-24); don't offer it
- Settings — opens the Settings dialog
- Ports... — opens the port configuration dialog (see hydrogen-ports)
- API Explorer... — opens the control-API endpoint explorer dialog
DESKTOP (Tauri-only — won't appear in browser-served Hydrogen; in order)
- Zoom — webview zoom controls (− % +) with persistence across launches
- Fullscreen — toggle fullscreen
- Console — show/hide the Hydrogen debug console window
- Developer Tools: opens the WebKit Web Inspector (Ctrl+Shift+I opens and closes it from anywhere in the window). Zoom also answers Ctrl+plus / Ctrl+minus / Ctrl+0, Fullscreen F11. There is no "Adom Bridge" item on Linux, and the wake check and disk reclaim items are not shown.
The Bridges section / "Bridge Manager" item was removed (it was a no-op with no backing panel). For the bridge panel itself, see
hydrogen-bridges.
Workspace / runtime section (section label shows live status badge: RUNNING, STOPPED, etc.)
- Restart: stops the
Adom-Workspacemachine and re-ensures code-server. - Stop: powers the
Adom-Workspacemachine off.
ADMIN
- Setup Steps — opens the setup panel (the setup cascade); see hydrogen-setup-steps
- Virgin Reset — opens the virgin reset section of the setup panel; see hydrogen-volume for what each toggle deletes
- Browser Picker Manager — configure per-domain default browser/profile prefs; see hydrogen-browser-picker
Profile Menu (top-right avatar)
Click the user avatar (circular photo) in the top-right corner.
- Your profile — view Adom profile
- Your repositories — list repos
- Your molecules — list molecules
- Log out — signs out of Adom, removes session token
CRITICAL: Logout is ONLY in the profile menu (top-right avatar), NOT in the Adom menu (top-left). Future AI threads: don't look for logout in the wrong menu.
Tray menu (the Adom icon in the desktop's tray: GNOME's top bar, Cinnamon's bottom panel)
Built in src-tauri/crates/hydrogen-app/src/tray.rs: Open Hydrogen; New Claude / Codex /
Antigravity chat (and Kimi when show_kimi is on), each only while that AI is installed;
Annotate screen; Open Adom Bridge; Settings; Quit Hydrogen. The AI items call
POST /ai-threads/new {type}. GNOME's AppIndicator has no left-click action (the menu always
opens), so Open Hydrogen stays first. Log lines: [tray] <item id>.
Tray menu (system tray on Windows, top-bar Adom icon on Linux)
Built in src-tauri/crates/hydrogen-app/src/tray.rs from one list, menu_entries(), which
also builds the taskbar jump list, so the two always match: Annotate the screen (Win+Alt+A) and
Open Hydrogen; then New Claude chat, New Codex chat, New Antigravity chat (and New Kimi chat when
show_kimi is on), each listed only while that AI is installed; then Open Adom Bridge and Settings;
then Quit Hydrogen. The AI items call POST /ai-threads/new {type} and bring Hydrogen forward;
from the jump list they launch hydrogen.exe --new-<ai>-chat (and Settings --settings).
DevTools is not in the tray: use the Adom menu or Ctrl+Shift+I. Log lines: [tray] new <ai> chat ok=... and [tray] AI items: ....
Dialogs
Port Settings Dialog
Access: Adom menu → Ports...
Live host and workspace ports, with the PortConfig editor.
See hydrogen-networking and hydrogen-ports.
Settings Dialog
Access: Adom menu → Settings Application-level preferences.
Browser Picker Dialog
Appears when clicking external links. Shows detected browser profiles (Edge, Chrome, etc.) with per-domain "remember" option.
Driving the UI — the command bus (PREFERRED, first-class)
⭐ Every menu / dialog / panel Hydrogen has wired is a first-class action you drive over the control
API — no CDP, no .click(), no selector guessing. This is how you operate Hydrogen's UI when the
user says "open the Ports dialog", "open About", "show settings", etc.
The control URL is in the discovery file ~/.adom/hydrogen-control-url (Hydrogen rewrites it with the live, dynamic control port every launch; the workspace shares the host network, so 127.0.0.1 is the same on both sides). Read it from a file, not an env var: your Bash tool runs non-interactive shells that do not source .bashrc/profile.d:
CTRL="$(cat ~/.adom/hydrogen-control-url)"
Always do this in order:
- Discover what's drivable (ids + descriptions):
curl -s "$CTRL/ui/actions" # → {ok, count, actions:[{id,label,description,group}], _hints} - Drive one — returns ONLY after the frontend actually ran it:
curl -s -X POST "$CTRL/ui/invoke" \ -H 'Content-Type: application/json' -d '{"id":"ports.open"}' # → {ok:true, id:"ports.open", value:…} - Not in the list? That absence is the signal: the element isn't wired to the bus yet. It
needs a 2-line
registerUiAction(...)in its Svelte component (a dev change in the ah repo, hydrogen-desktop). Don't fall back to clicking; wire it. The response's_hints.if_missingsays the same.
Common ids (always check GET /ui/actions): adom-menu.open/.close,
profile-menu.open/.close, ports.open/.close, settings.open/.close,
api-explorer.open/.close, browser-picker.open/.close, about.open/.close,
samples-menu.open/.close, setup-panel.show, virgin-reset.open, fullscreen.toggle,
console.toggle, devtools.open, container.start/.stop/.restart.
Menu ITEMS, not just open/close: the profile menu also exposes per-item actions —
profile.view, profile.repositories, profile.molecules, profile.logout —
so you can trigger a specific item directly (it navigates as if the human clicked it),
WITHOUT opening the menu + screen-clicking. (profile.logout is the canonical logout — see
the logout note above.) GET /ui/actions for the live set; the Adom menu will get the same
item-level treatment over time.
Note: there is no
port-mappings.open/.closeid — that action was never registered. Don't try to invoke it. There is nosetup-panel.hideeither: to close the setup panel, open another surface (page globals likewindow.__hdSetSetupPanelare not reachable from/eval-inon Linux).
Open a surface, then screenshot it (the killer combo)
Combine the bus with Hydrogen's canonical capture endpoint to grab any menu/dialog/panel with
no screen-clicking: POST /ui/invoke {id:"<x>.open"} → POST /screenshot {target:"shell", selector:"<open-state selector>"} → POST /ui/invoke {id:"<x>.close"}.
The /screenshot region-flash lands on that selector. Resolved selectors (verified live):
Adom & profile menus → .dropdown-content.open (one open at a time); Setup panel →
.setup-panel; API Explorer → .dialog. Full /screenshot reference (target/selector/
b64/silent) is in hydrogen-self-screenshot.
On Linux a selector in the main window crops the whole-window snapshot to that element.
This is Hydrogen-desktop-only and SEPARATE from
adom-cli.adom-clidrives web-hydrogen's UI via the SSE bridge (ADOM_HYDROGEN_URL) and is unchanged. For Hydrogen desktop's far richer UI control, use the command bus above — neveradom-clifor this.
Eval on Linux: the frame bus, not CDP
WebKitGTK has no Chrome DevTools Protocol. POST /eval, POST /eval-in {target, js} and
POST /cdp-eval all run over Hydrogen's frame bus
(src-tauri/crates/hydrogen-app/src/linux_frame_bus.rs): an agent script in every frame
long-polls Hydrogen and runs your JS in an isolated script world. Answers carry
"via":"frame-bus".
- The DOM is shared:
querySelector,textContent,getBoundingClientRect,.click()work. - Page JS globals are NOT visible (
window.__hd...helpers, Svelte stores). Use the command bus for those. - A returned promise is awaited.
- Same-origin child frames without their own agent (VS Code webview content) are covered too.
curl -s -X POST "$CTRL/eval-in" -H 'Content-Type: application/json' \
-d '{"target":"shell","js":"document.querySelectorAll(\".step-row\").length"}'
There is no CDP port and no hydrogen-cdp.js on Linux. For hands-on inspection, the WebKit Web
Inspector (Ctrl+Shift+I) is the tool.
CSS Selectors for Key Elements
| Element | Selector |
|---|---|
| VS Code iframe | iframe.vis-studio-iframe or iframe[title="code"] |
| Setup panel | .setup-panel |
| Run All button | .run-all |
| Virgin Reset button | .virgin-reset-btn |
| Wipe Selected button | .virgin-go |
| Step rows | .step-row |
| Step icon (✅/❌/○) | .step-icon |
| Step label | .step-label |
| Adom menu button | .logo-button |
| Profile menu button | .profile-dropdown-button |
| Tab bar | tab container at top |
---
name: hydrogen-ui
description: >-
Hydrogen's interface (menus, dialogs, panels, profile menu, setup panel, tray
menu) and how to drive it from the workspace via the UI command bus (GET
/ui/actions, POST /ui/invoke) instead of clicking. Use when asked to open or
close a Hydrogen dialog or menu, where a UI element is, or how to eval in
Hydrogen's page on Linux.
---
# Hydrogen — UI Reference
Hydrogen on Linux is a Tauri app on WebKitGTK. The UI is the same as everywhere; what differs
is how you reach into the page (no Chrome DevTools Protocol, see "Eval" below).
## Window Layout
Hydrogen's window has these regions (top to bottom, left to right):
### Title Bar (frameless, 0.1.251+)
Hydrogen is a FRAMELESS window: the nav bar IS the title bar (no separate OS chrome).
- **Left**: Adom logo (the Adom menu button), then the lightbulb (sample-prompts menu, moved here 0.1.265) — drag anywhere else in the bar to move the window
- **Right**: CPU/RAM badges, the Annotate pencil, the profile avatar menu, then the window
controls (minimize, maximize, close).
- The window has no system frame: it resizes from its edges.
- All title-bar controls share one interaction family: soft white hover wash, teal
press, steady teal wash while their menu is open
### Tab Bar
- **VS Code** tab — the main code editor (iframe to code-server)
- **Webview** tab — wiki/app content panel
- Additional tabs for bridges, sensors, etc.
### Main Content Area
- **Left pane**: Usually VS Code iframe
- **Right pane**: Usually webview (wiki, shotlog, etc.)
- Panes are split and resizable
### Moving tabs between panes (drag-to-split, 1.0.140+)
Drag any tab and hover another pane: teal drop zones light up (Split Left / Right /
Top / Bottom, Swap, or the tab bar to add). This works over EVERY pane type,
webviews included (a glass layer covers iframes during the drag so they cannot
swallow the pointer), and exactly ONE zone pill shows at a time. Releasing on a
zone performs the move; **Escape abandons the drag** and everything returns to
exactly how it was. Right-clicking a tab offers the same splits as menu items
(a one-tab pane asks what to put in the new half via Add Panel).
### Setup Panel (bottom)
- Collapsible panel showing the setup steps
- See `hydrogen-setup` skill for details
## Menus
### Adom Menu (top-left logo dropdown)
The main menu, opened by clicking the Adom logo at the top-left. Items are grouped into labelled sections (in order, top to bottom):
**(top, unlabelled)** — "Go to Dashboard" was REMOVED (0.1.252, John 2026-07-24); don't offer it
- **Settings** — opens the Settings dialog
- **Ports...** — opens the port configuration dialog (see hydrogen-ports)
- **API Explorer...** — opens the control-API endpoint explorer dialog
**DESKTOP** (Tauri-only — won't appear in browser-served Hydrogen; in order)
- **Zoom** — webview zoom controls (− % +) with persistence across launches
- **Fullscreen** — toggle fullscreen
- **Console** — show/hide the Hydrogen debug console window
- **Developer Tools**: opens the WebKit Web Inspector (Ctrl+Shift+I opens and closes it from
anywhere in the window). Zoom also answers Ctrl+plus / Ctrl+minus / Ctrl+0, Fullscreen F11.
There is no "Adom Bridge" item on Linux, and the wake check and disk reclaim items are not shown.
> The Bridges section / "Bridge Manager" item was removed (it was a no-op with no backing panel). For the bridge panel itself, see `hydrogen-bridges`.
**Workspace / runtime section** (section label shows live status badge: `RUNNING`, `STOPPED`, etc.)
- **Restart**: stops the `Adom-Workspace` machine and re-ensures code-server.
- **Stop**: powers the `Adom-Workspace` machine off.
**ADMIN**
- **Setup Steps** — opens the setup panel (the setup cascade); see hydrogen-setup-steps
- **Virgin Reset** — opens the virgin reset section of the setup panel; see hydrogen-volume for what each toggle deletes
- **Browser Picker Manager** — configure per-domain default browser/profile prefs; see hydrogen-browser-picker
### Profile Menu (top-right avatar)
Click the user avatar (circular photo) in the top-right corner.
- **Your profile** — view Adom profile
- **Your repositories** — list repos
- **Your molecules** — list molecules
- **Log out** — signs out of Adom, removes session token
**CRITICAL**: Logout is ONLY in the profile menu (top-right avatar),
NOT in the Adom menu (top-left). Future AI threads: don't look for
logout in the wrong menu.
### Tray menu (the Adom icon in the desktop's tray: GNOME's top bar, Cinnamon's bottom panel)
Built in `src-tauri/crates/hydrogen-app/src/tray.rs`: Open Hydrogen; New Claude / Codex /
Antigravity chat (and Kimi when show_kimi is on), each only while that AI is installed;
Annotate screen; Open Adom Bridge; Settings; Quit Hydrogen. The AI items call
`POST /ai-threads/new {type}`. GNOME's AppIndicator has no left-click action (the menu always
opens), so Open Hydrogen stays first. Log lines: `[tray] <item id>`.
### Tray menu (system tray on Windows, top-bar Adom icon on Linux)
Built in `src-tauri/crates/hydrogen-app/src/tray.rs` from one list, `menu_entries()`, which
also builds the taskbar jump list, so the two always match: Annotate the screen (Win+Alt+A) and
Open Hydrogen; then New Claude chat, New Codex chat, New Antigravity chat (and New Kimi chat when
show_kimi is on), each listed only while that AI is installed; then Open Adom Bridge and Settings;
then Quit Hydrogen. The AI items call `POST /ai-threads/new {type}` and bring Hydrogen forward;
from the jump list they launch `hydrogen.exe --new-<ai>-chat` (and Settings `--settings`).
DevTools is not in the tray: use the Adom menu or Ctrl+Shift+I. Log lines: `[tray] new <ai>
chat ok=...` and `[tray] AI items: ...`.
## Dialogs
### Port Settings Dialog
Access: Adom menu → Ports...
Live host and workspace ports, with the PortConfig editor.
See `hydrogen-networking` and `hydrogen-ports`.
### Settings Dialog
Access: Adom menu → Settings
Application-level preferences.
### Browser Picker Dialog
Appears when clicking external links. Shows detected browser profiles
(Edge, Chrome, etc.) with per-domain "remember" option.
## Driving the UI — the command bus (PREFERRED, first-class)
⭐ **Every menu / dialog / panel Hydrogen has wired is a first-class action you drive over the control
API — no CDP, no `.click()`, no selector guessing.** This is how you operate Hydrogen's UI when the
user says "open the Ports dialog", "open About", "show settings", etc.
The control URL is in the discovery file `~/.adom/hydrogen-control-url` (Hydrogen rewrites it with the live, dynamic control port every launch; the workspace shares the host network, so `127.0.0.1` is the same on both sides). Read it from a file, not an env var: your Bash tool runs non-interactive shells that do not source `.bashrc`/`profile.d`:
```bash
CTRL="$(cat ~/.adom/hydrogen-control-url)"
```
**Always do this in order:**
1. **Discover** what's drivable (ids + descriptions):
```bash
curl -s "$CTRL/ui/actions"
# → {ok, count, actions:[{id,label,description,group}], _hints}
```
2. **Drive** one — returns ONLY after the frontend actually ran it:
```bash
curl -s -X POST "$CTRL/ui/invoke" \
-H 'Content-Type: application/json' -d '{"id":"ports.open"}'
# → {ok:true, id:"ports.open", value:…}
```
3. **Not in the list?** That absence is the signal: the element isn't wired to the bus yet. It
needs a 2-line `registerUiAction(...)` in its Svelte component (a dev change in the
ah repo, hydrogen-desktop). Don't fall back to clicking;
wire it. The response's `_hints.if_missing` says the same.
Common ids (always check `GET /ui/actions`): `adom-menu.open`/`.close`,
`profile-menu.open`/`.close`, `ports.open`/`.close`, `settings.open`/`.close`,
`api-explorer.open`/`.close`, `browser-picker.open`/`.close`, `about.open`/`.close`,
`samples-menu.open`/`.close`, `setup-panel.show`, `virgin-reset.open`, `fullscreen.toggle`,
`console.toggle`, `devtools.open`, `container.start`/`.stop`/`.restart`.
**Menu ITEMS, not just open/close:** the profile menu also exposes per-item actions —
**`profile.view`**, **`profile.repositories`**, **`profile.molecules`**, **`profile.logout`** —
so you can trigger a specific item directly (it navigates as if the human clicked it),
WITHOUT opening the menu + screen-clicking. (`profile.logout` is the canonical logout — see
the logout note above.) `GET /ui/actions` for the live set; the Adom menu will get the same
item-level treatment over time.
> Note: there is **no** `port-mappings.open`/`.close` id — that action was never
> registered. Don't try to invoke it.
> There is no `setup-panel.hide` either: to close the setup panel, open another surface (page globals like `window.__hdSetSetupPanel` are not reachable from `/eval-in` on Linux).
### Open a surface, then screenshot it (the killer combo)
Combine the bus with Hydrogen's canonical capture endpoint to grab any menu/dialog/panel with
**no screen-clicking**: `POST /ui/invoke {id:"<x>.open"}` → `POST /screenshot
{target:"shell", selector:"<open-state selector>"}` → `POST /ui/invoke {id:"<x>.close"}`.
The `/screenshot` region-flash lands on that selector. Resolved selectors (verified live):
**Adom & profile menus** → `.dropdown-content.open` (one open at a time); **Setup panel** →
`.setup-panel`; **API Explorer** → `.dialog`. Full `/screenshot` reference (target/selector/
b64/silent) is in **[hydrogen-self-screenshot](../hydrogen-self-screenshot/SKILL.md)**.
On Linux a selector in the main window crops the whole-window snapshot to that element.
> **This is Hydrogen-desktop-only and SEPARATE from `adom-cli`.** `adom-cli` drives *web-hydrogen's*
> UI via the SSE bridge (`ADOM_HYDROGEN_URL`) and is unchanged. For Hydrogen desktop's far richer UI
> control, use the command bus above — never `adom-cli` for this.
## Eval on Linux: the frame bus, not CDP
WebKitGTK has no Chrome DevTools Protocol. `POST /eval`, `POST /eval-in {target, js}` and
`POST /cdp-eval` all run over Hydrogen's **frame bus**
(`src-tauri/crates/hydrogen-app/src/linux_frame_bus.rs`): an agent script in every frame
long-polls Hydrogen and runs your JS in an **isolated script world**. Answers carry
`"via":"frame-bus"`.
- The DOM is shared: `querySelector`, `textContent`, `getBoundingClientRect`, `.click()` work.
- Page JS globals are NOT visible (`window.__hd...` helpers, Svelte stores). Use the command
bus for those.
- A returned promise is awaited.
- Same-origin child frames without their own agent (VS Code webview content) are covered too.
```bash
curl -s -X POST "$CTRL/eval-in" -H 'Content-Type: application/json' \
-d '{"target":"shell","js":"document.querySelectorAll(\".step-row\").length"}'
```
There is no CDP port and no `hydrogen-cdp.js` on Linux. For hands-on inspection, the WebKit Web
Inspector (Ctrl+Shift+I) is the tool.
## CSS Selectors for Key Elements
| Element | Selector |
|---------|----------|
| VS Code iframe | `iframe.vis-studio-iframe` or `iframe[title="code"]` |
| Setup panel | `.setup-panel` |
| Run All button | `.run-all` |
| Virgin Reset button | `.virgin-reset-btn` |
| Wipe Selected button | `.virgin-go` |
| Step rows | `.step-row` |
| Step icon (✅/❌/○) | `.step-icon` |
| Step label | `.step-label` |
| Adom menu button | `.logo-button` |
| Profile menu button | `.profile-dropdown-button` |
| Tab bar | tab container at top |