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-browser-picker description: >- Hydrogen's Browser Picker on Linux: how URLs opened in Hydrogen are caught and routed (native browser profile, Hydrogen tab or window, Pup), the quiet remember-per-website mode, the countdown, and how Linux browsers and profiles are detected. Use when a link won't open, the picker lists no browsers, for oauth or sign-in links, or adding a URL-opening feature.
Hydrogen Browser Picker (Linux)
The Problem
Hydrogen wraps a WebKitGTK webview that contains:
- The Hydrogen SvelteKit frontend (localhost:1420 in DEV mode only; prod Hydrogen serves it via the tauri protocol)
- The code-server iframe (VS Code + Claude Code) on port 7380
- Webview panel iframes (any external URL like wiki, google, etc.)
When a link is clicked anywhere in this stack, Hydrogen needs to:
- Catch it before it opens uncontrolled
- Route it through the Browser Picker dialog
- Let the user choose: native browser (Chrome/Edge), Hydrogen Tab (wv), Hydrogen Browser Window (short name: hbw), or Pup
Links open without asking (remember per website)
With Settings > Hydrogen > Behavior > "When a link opens" on Remember per website (the
default, setting hydrogen.link_open_mode):
- A link opens where that website's links went last time, or at the picker's usual default (saved domain pref, then the bias file, then the work profile).
- A toast says where ("Opened example.org in Firefox ([email protected])") with a Change button that reopens the full picker for the same link; a pick there is remembered.
- Sign-in links and "move this page" (
-movetriggers) still show the picker every time. - Always ask brings back the picker plus countdown on every link.
- Shift-click does not force the picker on Linux (Shift is not detected). Use Change on the
toast, or
POST /open-url {"url":..., "force":true}.
How links are caught on Linux (WebKitGTK)
| Event | Caught by | Result |
|---|---|---|
window.open() / target="_blank" from the app or the editor (VS Code openExternal, extension links) |
Tauri on_new_window |
Browser Picker |
VS Code's window.open('') then location = url |
frame-bus script turns '' into about:blank; Hydrogen grants a managed popup (hd-popup-*) whose outside navigation goes to the picker, then the empty popup closes |
Browser Picker |
| The main page itself starting to load an outside http(s) URL | GTK load-changed guard on the main frame: the load is stopped |
Browser Picker |
| Link inside a webview tab iframe | not intercepted | navigates the iframe |
mailto: / tel: / sms: in any frame |
frame bus app-link handler | the desktop's default app, or the address copied to the clipboard if none |
Hydrogen turns on WebKitGTK's javascript-can-open-windows-automatically for the main webview so
scripted popups reach on_new_window at all (otherwise code-server shows "The browser blocked
opening a new window"). There is no "Open Link with Browser Picker" item in the right-click menu
on Linux.
Browser Picker Dialog
src/lib/components/BrowserProfileDialog.svelte
3 Branded Variants
- Claude auth — Claude logo, "Connect to Claude Code" (domains:
*.claude.ai,*.claude.com) - Adom auth — Adom logo, "Sign in to Hydrogen" (domains:
*.adom.inc+/auth/intent) - General link — "Browser Picker" title, no logo
On Linux, other AI sign-ins count as sign-ins too: auth.openai.com, accounts.google.com, Kimi /
Moonshot, x.ai, login.microsoftonline.com, GitHub device login, any /oauth/authorize,
/oauth2/auth or /device URL. For sign-ins the Hydrogen section starts collapsed, so native
browsers come first (those pages refuse to load inside Hydrogen), and the fresh-window toggle
starts on.
Consistent Elements (all variants)
- "Browser Picker" title at top
- Native Browsers section with real Google profile avatars
- Hydrogen section (collapsible, collapsed for auth)
- Details section (collapsible, collapsed) — URL, remember checkbox, trigger info, build version
- Auto-timer with progress bar (cancelled by mouse movement): 5 s for links, 10 s for sign-ins
- Keyboard navigation (arrow keys + Enter)
- 800ms delayed tooltips
Auto-Timer Behavior
- Picks best default: the saved domain pref, then the bias file, then the work browser profile (non-gmail email)
- 5-second countdown for links, 10 seconds for sign-ins, with a progress bar
- ANY mouse movement cancels the timer
force:trueon/open-urlshows the dialog without the timer (Shift is not detected on Linux)- Selected destination highlighted with teal border
Fresh-window option
fresh:true opens a brand-new browser window rather than a tab. It does not force the
foreground: on Linux the window manager decides focus.
- Mechanism: Chromium-family browsers get
--new-windowand Firefox-new-windowbefore the URL. With no concrete browser program,xdg-openis the fallback, which loses profile and fresh. - UI: an "Open in a fresh window" checkbox above the Native Browsers list. Defaulted
ON for auth URLs (Claude/Adom), OFF otherwise. Only native-browser destinations honor
it; internal Hydrogen destinations ignore it. The dialog dispatches
selectwithfresh: dest.category==='native' ? freshWindow : false;onProfileSelectthreads it toopen_in_browser_profile//open-in-profile. freshis honored by: Tauriopen_in_browser_profile(direct),POST /open-in-profile(direct), andPOST /open-url(where it pre-seeds the picker's toggle; adddirect:trueto open immediately instead). Direct paths echo{"fresh":…, "method":"<exe … fresh-window>"}.
URL Event Deduplication
The frontend drops a repeat of the same URL within 1 second, so several handlers firing for one click open it once.
Prefs Sync
Preferences re-read from localStorage on every dialog open. If user deletes a domain in Browser Picker Manager, the next dialog open reflects it immediately.
Browser detection (hydrogen-control-ui/src/linux_browsers.rs)
- Programs: each browser's commands on PATH plus
/snap/bin, and Flatpak exports (system and per-user): Firefox (firefox,firefox-esr), Chrome (google-chrome-stable), Chromium, Edge, Brave, Vivaldi, Opera. - Profiles: Chromium-family
Default/Profile Ndirs under~/.config(and the snap and Flatpak homes); Firefox profiles fromprofiles.ini(~/.mozilla,~/.config/mozilla, snap, Flatpak), only ones that have been used, with the Firefox Account email when signed in. - Default browser:
xdg-settings get default-web-browser, thenmimeapps.list. - Launch: Chromium-family with
--profile-directory=<dir>; FirefoxDefaultwithout-P(reuses the running Firefox), any other profile with-P <name>.freshadds--new-window/-new-window. With no concrete program,xdg-open(viaopen::that) is the fallback, which loses profile and fresh.
"The picker lists no browsers": check the browser runs from a terminal by one of the names above, and that a profile has been used at least once.
Files
| File | What |
|---|---|
src-tauri/crates/hydrogen-app/src/lib.rs |
on_new_window, granted popups, the Linux main-frame guard, dispatch_url_event, linux_open_app_link |
src-tauri/crates/hydrogen-app/src/linux_frame_bus.rs |
window.open('') fix and the app-link handler in every frame |
src-tauri/crates/hydrogen-control-ui/src/linux_browsers.rs |
browser, profile and default detection |
src/lib/components/BrowserProfileDialog.svelte |
Browser Picker dialog (3 variants, auto-timer, keyboard nav) |
src/lib/components/editor/EditorNav.svelte |
Browser Picker Manager modal |
src/routes/+layout.svelte |
CustomEvent listeners, URL event parsing, deduplication |
src/lib/assets/claude-logo.svg |
Real Claude logo from claude.ai/favicon.svg |
src/lib/assets/adom-logo-teal.svg |
Adom brand logo |
src/lib/buildVersion.ts |
Build version tracking for verification |
The auto-countdown (why AI loves it)
The picker opens with a countdown on its best-default destination. If nothing interrupts, the URL auto-routes there. This is the key feature for AI automation: triggers like OAuth redirects, "open in browser" links, or wiki references work hands-free.
- AI scripts can fire a URL open and the right thing happens within seconds: no clicking, no blocking on a dialog.
- Mouse movement cancels the timer — if a human is at the keyboard, just wiggle the mouse and the picker waits.
AI automation recipe
BASE="$(cat ~/.adom/hydrogen-control-url)"
curl -s -X POST -H 'Content-Type: application/json' -d '{"url":"https://example.com"}' "$BASE/open-url"
curl -s -X POST -H 'Content-Type: application/json' -d '{"url":"https://example.com","force":true}' "$BASE/open-url"
curl -s -X POST -H 'Content-Type: application/json' \
-d '{"url":"https://example.com","browser":"firefox","profileDir":"Default","fresh":true}' "$BASE/open-in-profile"
/open-url ROUTES THROUGH THE PICKER by default (emits browser-open-request):
fresh pre-seeds the "Open in a fresh window" toggle, force:true skips the 5s
auto-timer, direct:true (or naming a concrete browser) bypasses the picker and
opens immediately. The response routed field is "browser-picker" or "direct".
/open-in-profile always opens directly (no picker). signin:true on Linux always opens
directly in the system browser. Read method in the reply before claiming success.
Prefs are now an API — the picker is a FALLBACK, not a gate
The per-domain routing memory is CRUD over the control API, so the AI governs routing and
the picker only pops for a domain with no policy + no direct call:
GET /browser-picker/prefs (read {domains:{<host>:{destination,label}}}),
PUT /browser-picker/prefs {domain,destination,label?} (set/override),
DELETE /browser-picker/prefs/<host> (forget one), DELETE /browser-picker/prefs (clear all).
destination is an ID: hydrogen-tab (wv) | webview-window (hbw — Hydrogen's standalone Tauri browser window; also POST /hbw/open; close one with POST /hbw/close {"label":"hbw-<ts>"}, hbw labels only, from 1.0.142) | pup-window (pup), or a native id (nb): users address these as nb <browser> [profile] — "nb chrome work", "nb edge" — resolve via GET /browser-profiles; the id form is
browser:<browser>:<dir> (profile dir encoded in the ID). fresh is per-open, not stored.
Writes hit the Manager's live state (localStorage + hydrogen-url-routing-prefs-changed). Full
routing-policy guidance lives in hydrogen-open-url.
---
name: hydrogen-browser-picker
description: >-
Hydrogen's Browser Picker on Linux: how URLs opened in Hydrogen are caught and
routed (native browser profile, Hydrogen tab or window, Pup), the quiet
remember-per-website mode, the countdown, and how Linux browsers and profiles
are detected. Use when a link won't open, the picker lists no browsers, for
oauth or sign-in links, or adding a URL-opening feature.
---
# Hydrogen Browser Picker (Linux)
## The Problem
Hydrogen wraps a WebKitGTK webview that contains:
- The Hydrogen SvelteKit frontend (localhost:1420 in DEV mode only; prod Hydrogen serves it via the tauri protocol)
- The code-server iframe (VS Code + Claude Code) on port 7380
- Webview panel iframes (any external URL like wiki, google, etc.)
When a link is clicked anywhere in this stack, Hydrogen needs to:
1. Catch it before it opens uncontrolled
2. Route it through the Browser Picker dialog
3. Let the user choose: native browser (Chrome/Edge), Hydrogen Tab (wv), Hydrogen Browser Window (short name: **hbw**), or Pup
## Links open without asking (remember per website)
With Settings > Hydrogen > Behavior > "When a link opens" on **Remember per website** (the
default, setting `hydrogen.link_open_mode`):
- A link opens where that website's links went last time, or at the picker's usual default (saved
domain pref, then the bias file, then the work profile).
- A toast says where ("Opened example.org in Firefox ([email protected])") with a **Change** button that
reopens the full picker for the same link; a pick there is remembered.
- Sign-in links and "move this page" (`-move` triggers) still show the picker every time.
- **Always ask** brings back the picker plus countdown on every link.
- Shift-click does not force the picker on Linux (Shift is not detected). Use **Change** on the
toast, or `POST /open-url {"url":..., "force":true}`.
## How links are caught on Linux (WebKitGTK)
| Event | Caught by | Result |
|---|---|---|
| `window.open()` / `target="_blank"` from the app or the editor (VS Code `openExternal`, extension links) | Tauri `on_new_window` | Browser Picker |
| VS Code's `window.open('')` then `location = url` | frame-bus script turns `''` into `about:blank`; Hydrogen grants a managed popup (`hd-popup-*`) whose outside navigation goes to the picker, then the empty popup closes | Browser Picker |
| The main page itself starting to load an outside http(s) URL | GTK `load-changed` guard on the main frame: the load is stopped | Browser Picker |
| Link inside a webview tab iframe | not intercepted | navigates the iframe |
| `mailto:` / `tel:` / `sms:` in any frame | frame bus app-link handler | the desktop's default app, or the address copied to the clipboard if none |
Hydrogen turns on WebKitGTK's `javascript-can-open-windows-automatically` for the main webview so
scripted popups reach `on_new_window` at all (otherwise code-server shows "The browser blocked
opening a new window"). There is no "Open Link with Browser Picker" item in the right-click menu
on Linux.
## Browser Picker Dialog
`src/lib/components/BrowserProfileDialog.svelte`
### 3 Branded Variants
1. **Claude auth** — Claude logo, "Connect to Claude Code" (domains: `*.claude.ai`, `*.claude.com`)
2. **Adom auth** — Adom logo, "Sign in to Hydrogen" (domains: `*.adom.inc` + `/auth/intent`)
3. **General link** — "Browser Picker" title, no logo
On Linux, other AI sign-ins count as sign-ins too: auth.openai.com, accounts.google.com, Kimi /
Moonshot, x.ai, login.microsoftonline.com, GitHub device login, any `/oauth/authorize`,
`/oauth2/auth` or `/device` URL. For sign-ins the Hydrogen section starts collapsed, so native
browsers come first (those pages refuse to load inside Hydrogen), and the fresh-window toggle
starts on.
### Consistent Elements (all variants)
- "Browser Picker" title at top
- Native Browsers section with real Google profile avatars
- Hydrogen section (collapsible, collapsed for auth)
- Details section (collapsible, collapsed) — URL, remember checkbox, trigger info, build version
- Auto-timer with progress bar (cancelled by mouse movement): 5 s for links, 10 s for sign-ins
- Keyboard navigation (arrow keys + Enter)
- 800ms delayed tooltips
### Auto-Timer Behavior
- Picks best default: the saved domain pref, then the bias file, then the work browser profile
(non-gmail email)
- 5-second countdown for links, 10 seconds for sign-ins, with a progress bar
- ANY mouse movement cancels the timer
- `force:true` on `/open-url` shows the dialog without the timer (Shift is not detected on Linux)
- Selected destination highlighted with teal border
### Fresh-window option
`fresh:true` opens a brand-new browser window rather than a tab. It does not force the
foreground: on Linux the window manager decides focus.
- Mechanism: Chromium-family browsers get `--new-window` and Firefox `-new-window` before the
URL. With no concrete browser program, `xdg-open` is the fallback, which loses profile and fresh.
- UI: an **"Open in a fresh window"** checkbox above the Native Browsers list. **Defaulted
ON for auth URLs** (Claude/Adom), OFF otherwise. Only native-browser destinations honor
it; internal Hydrogen destinations ignore it. The dialog dispatches `select` with
`fresh: dest.category==='native' ? freshWindow : false`; `onProfileSelect` threads it to
`open_in_browser_profile` / `/open-in-profile`.
- `fresh` is honored by: Tauri `open_in_browser_profile` (direct), `POST /open-in-profile`
(direct), and `POST /open-url` (where it **pre-seeds the picker's toggle**; add
`direct:true` to open immediately instead). Direct paths echo
`{"fresh":…, "method":"<exe … fresh-window>"}`.
### URL Event Deduplication
The frontend drops a repeat of the same URL within 1 second, so several handlers firing for
one click open it once.
### Prefs Sync
Preferences re-read from localStorage on every dialog open. If user deletes a domain in Browser Picker Manager, the next dialog open reflects it immediately.
## Browser detection (`hydrogen-control-ui/src/linux_browsers.rs`)
- **Programs:** each browser's commands on PATH plus `/snap/bin`, and Flatpak exports (system and
per-user): Firefox (`firefox`, `firefox-esr`), Chrome (`google-chrome-stable`), Chromium,
Edge, Brave, Vivaldi, Opera.
- **Profiles:** Chromium-family `Default` / `Profile N` dirs under `~/.config` (and the snap and
Flatpak homes); Firefox profiles from `profiles.ini` (`~/.mozilla`, `~/.config/mozilla`, snap,
Flatpak), only ones that have been used, with the Firefox Account email when signed in.
- **Default browser:** `xdg-settings get default-web-browser`, then `mimeapps.list`.
- **Launch:** Chromium-family with `--profile-directory=<dir>`; Firefox `Default` without `-P`
(reuses the running Firefox), any other profile with `-P <name>`. `fresh` adds `--new-window`
/ `-new-window`. With no concrete program, `xdg-open` (via `open::that`) is the fallback, which
loses profile and fresh.
"The picker lists no browsers": check the browser runs from a terminal by one of the names above,
and that a profile has been used at least once.
## Files
| File | What |
|---|---|
| `src-tauri/crates/hydrogen-app/src/lib.rs` | `on_new_window`, granted popups, the Linux main-frame guard, `dispatch_url_event`, `linux_open_app_link` |
| `src-tauri/crates/hydrogen-app/src/linux_frame_bus.rs` | `window.open('')` fix and the app-link handler in every frame |
| `src-tauri/crates/hydrogen-control-ui/src/linux_browsers.rs` | browser, profile and default detection |
| `src/lib/components/BrowserProfileDialog.svelte` | Browser Picker dialog (3 variants, auto-timer, keyboard nav) |
| `src/lib/components/editor/EditorNav.svelte` | Browser Picker Manager modal |
| `src/routes/+layout.svelte` | CustomEvent listeners, URL event parsing, deduplication |
| `src/lib/assets/claude-logo.svg` | Real Claude logo from claude.ai/favicon.svg |
| `src/lib/assets/adom-logo-teal.svg` | Adom brand logo |
| `src/lib/buildVersion.ts` | Build version tracking for verification |
## The auto-countdown (why AI loves it)
The picker opens with a countdown on its best-default destination. If nothing interrupts, the URL auto-routes there. This is the key feature for AI automation: triggers like OAuth redirects, "open in browser" links, or wiki references work hands-free.
- **AI scripts can fire a URL open and the right thing happens within seconds**: no clicking, no blocking on a dialog.
- **Mouse movement cancels the timer** — if a human is at the keyboard, just wiggle the mouse and the picker waits.
## AI automation recipe
```bash
BASE="$(cat ~/.adom/hydrogen-control-url)"
curl -s -X POST -H 'Content-Type: application/json' -d '{"url":"https://example.com"}' "$BASE/open-url"
curl -s -X POST -H 'Content-Type: application/json' -d '{"url":"https://example.com","force":true}' "$BASE/open-url"
curl -s -X POST -H 'Content-Type: application/json' \
-d '{"url":"https://example.com","browser":"firefox","profileDir":"Default","fresh":true}' "$BASE/open-in-profile"
```
`/open-url` ROUTES THROUGH THE PICKER by default (emits `browser-open-request`):
`fresh` pre-seeds the "Open in a fresh window" toggle, `force:true` skips the 5s
auto-timer, `direct:true` (or naming a concrete `browser`) bypasses the picker and
opens immediately. The response `routed` field is `"browser-picker"` or `"direct"`.
`/open-in-profile` always opens directly (no picker). `signin:true` on Linux always opens
directly in the system browser. Read `method` in the reply before claiming success.
## Prefs are now an API — the picker is a FALLBACK, not a gate
The per-domain routing memory is CRUD over the control API, so the **AI governs routing** and
the picker only pops for a domain with no policy + no direct call:
`GET /browser-picker/prefs` (read `{domains:{<host>:{destination,label}}}`),
`PUT /browser-picker/prefs {domain,destination,label?}` (set/override),
`DELETE /browser-picker/prefs/<host>` (forget one), `DELETE /browser-picker/prefs` (clear all).
`destination` is an ID: `hydrogen-tab` (wv) | `webview-window` (**hbw** — Hydrogen's standalone Tauri browser window; also `POST /hbw/open`; close one with `POST /hbw/close {"label":"hbw-<ts>"}`, hbw labels only, from 1.0.142) | `pup-window` (pup), or a native id (**nb**): users address these as `nb <browser> [profile]` — "nb chrome work", "nb edge" — resolve via GET /browser-profiles; the id form is
`browser:<browser>:<dir>` (profile dir encoded in the ID). `fresh` is per-open, not stored.
Writes hit the Manager's live state (localStorage + `hydrogen-url-routing-prefs-changed`). Full
routing-policy guidance lives in **[hydrogen-open-url](../hydrogen-open-url/SKILL.md)**.