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-eval description: >- Inject JavaScript into any surface of the Hydrogen window (app shell, VS Code workbench, wiki panel, Claude chat) through POST /eval-in, which runs over Hydrogen's frame bus on Linux. Use when asked to inject a UI add-on, add a demo arrow or overlay, highlight an element, or read the DOM of the Hydrogen window.
hydrogen-eval: inject JS into any Hydrogen surface (POST /eval-in)
The Hydrogen window is a tree of frames, not one page:
| friendly target | what it is | typical use |
|---|---|---|
shell |
the Hydrogen app shell (Svelte): top nav, logo menu, dialogs, the floating layer | inject add-ons/overlays that float over everything |
workbench |
the VS Code editor (code-server) | activity bar, tabs, the "Claude Code: Open" button |
wiki |
the wiki panel iframe | wiki DOM |
claude |
the Claude Code chat webview (only exists while the panel is open) | the chat input + send button |
How it runs on Linux: the frame bus
WebKitGTK has no Chrome DevTools Protocol. Hydrogen injects an agent script into every frame,
in an isolated script world, and /eval-in sends your JS to the frame you name over that
bus (hydrogen-app/src/linux_frame_bus.rs). What that means for you:
- The DOM is shared, page JS globals are not.
document.querySelector, events,click(),execCommand, styles and IndexedDB all work. A page's own globals (Svelte stores, awindow.__somethingthe page defined) are invisible: drive the DOM, not the page's functions. - Context ids are the agent's random ids, stable for the frame's life. Don't keep them across reloads.
- No surface list:
GET /targetsand a/eval-incall withoutjsreturn nothing on Linux. A miss returns an error that names every candidate frame, which is the discovery. - Same-origin child frames without their own agent (VS Code webview content) are reached
through their parent's agent, so the Claude chat is still
target:"claude".
Reaching the control API
The workspace shares the host's network, so the API is on 127.0.0.1. Read the live URL from
the discovery file:
BASE="$(cat ~/.adom/hydrogen-control-url)" # http://127.0.0.1:<dynamic>
(Never hardcode the port — read the live URL from ~/.adom/hydrogen-control-url.)
The call
POST /eval-in
{
"target": "shell" | "workbench" | "wiki" | "claude" | "<url-substring>" | "<id>",
"js": "<javascript; value of last expression is returned>",
"find": "<OPTIONAL JS expression>", // disambiguate among same-origin contexts
"frame": "<url-substring | index>", // OPTIONAL nested-context selector
}
→ { "ok": true, "value": <result>, "target": "<matched url>", "contextId": N, "frames": [...] }
A returned promise is always awaited on Linux.
find — the important one
The workbench has several same-origin frames. Origin alone is ambiguous, so pass find:
a JS expression (e.g. document.querySelector('...'), NOT a bare CSS selector).
/eval-in evals it in each candidate context and runs your js in the first
one where find is truthy.
Recipes
Add-on: a widget in the top nav (e.g. a usage meter) — target shell
Inject once; it persists until reload. Append your element to nav in the shell.
Demo overlay: a red arrow over everything that you reposition — target shell
Inject a position:fixed; z-index:2147483647; pointer-events:none element with a
CSS transition into the shell body, then move it with cheap follow-up evals
(it glides). The shell floats over all iframes, so window coords work everywhere.
Highlight an element (even deep in the workbench / Claude webview)
Eval inside the element's own surface and set outline — no coordinate math.
Use find to land in the right context, e.g.
find: document.querySelector("a[aria-label='Claude Code: Open']").
Type into & submit the Claude chat (panel must be open)
Stable selectors (NOT the CSS-module hash classes like .messageInput_xxxx,
which change per build):
- input =
[aria-label='Message input'](acontenteditablediv) — focus it, thendocument.execCommand('insertText', false, text). - submit =
button[type='submit'][data-permission-mode](disabled until text) —.click()it; fallback = dispatch anEnterkeydown on the input. Prefer the/claude/injectendpoints for this (see hydrogen-claude-management).
Verify-then-fallback (recommended)
/eval-in returns the JS value, so always verify: after an action, eval a probe
and check it; if it fails, try a second technique.
Don'ts
- Don't hardcode the control port — read
/ports. - Don't pass
findas a bare CSS selector — it's a JS expression. - Don't select by CSS-module hash classes — use stable attributes (
aria-label,data-*,role). - Don't expect the
claudewebview to exist unless the Claude panel is open. - Don't use
/evalfor workbench/Claude — it only reaches the shell page. /iframe-evalis CDP-only and does nothing useful on Linux.- Don't call page globals: the isolated world cannot see them.
Cross-references
- hydrogen-api — the full control API surface
- hydrogen-ui / hydrogen-adom-menu — where UI elements live
- hydrogen-self-screenshot — capture the result of your injection
Recipe: hide/show activity-bar icons (the RIGHT way — persisted, overflow-proof)
Do NOT hide activity-bar icons with display:none on .action-item — that misses
icons collapsed into the "…" (Additional Views) overflow and doesn't persist.
Instead write VS Code's own source-of-truth state, then reload the workbench:
- DB:
vscode-web-state-db-global→ storeItemTable→ keyworkbench.activity.pinnedViewlets2 - It's an array of
{id, pinned, visible, order}. Setpinned:falseto hide an icon from the activity bar (works even if it's in the overflow),pinned:trueto restore. - IDs: Explorer
workbench.view.explorer· Searchworkbench.view.search· Source Controlworkbench.view.scm· Run&Debugworkbench.view.debug· Extensionsworkbench.view.extensions(extension views:workbench.view.extension.<id>). - IndexedDB is per-origin, so read/write from any
localhost:7380context (targetworkbench,find: "(typeof indexedDB!=='undefined')") — don't require the workbench main doc (it's absent during a reload). - After writing, reload the workbench (
iframe.src=iframe.srcon theshell, orPOST /reload-vscode) so VS Code re-readspinnedViewlets2.
// hide Search / Source Control / Run&Debug (then reload)
{ "target":"workbench", "find":"(typeof indexedDB!=='undefined')", "awaitPromise":true,
"js":"(async function(){function g(d,k){return new Promise(function(r){var o=indexedDB.open(d);o.onsuccess=function(){var b=o.result;var q=b.transaction('ItemTable','readonly').objectStore('ItemTable').get(k);q.onsuccess=function(){b.close();r(q.result)}}})}function p(d,k,v){return new Promise(function(r){var o=indexedDB.open(d);o.onsuccess=function(){var b=o.result;var t=b.transaction('ItemTable','readwrite');t.objectStore('ItemTable').put(v,k);t.oncomplete=function(){b.close();r(true)}}})}var DB='vscode-web-state-db-global',K='workbench.activity.pinnedViewlets2';var a=JSON.parse(await g(DB,K));var ids=['workbench.view.search','workbench.view.scm','workbench.view.debug'];a.forEach(function(e){if(ids.indexOf(e.id)>-1)e.pinned=false});await p(DB,K,JSON.stringify(a));return 'hidden';})()" }
POST /vscode/hide-activity-items does the same job server-side.
---
name: hydrogen-eval
description: >-
Inject JavaScript into any surface of the Hydrogen window (app shell, VS Code workbench,
wiki panel, Claude chat) through POST /eval-in, which runs over Hydrogen's frame bus on
Linux. Use when asked to inject a UI add-on, add a demo arrow or overlay, highlight an
element, or read the DOM of the Hydrogen window.
---
# hydrogen-eval: inject JS into any Hydrogen surface (`POST /eval-in`)
The Hydrogen window is a tree of frames, not one page:
| friendly target | what it is | typical use |
|---|---|---|
| `shell` | the Hydrogen app shell (Svelte): top nav, logo menu, dialogs, the floating layer | inject add-ons/overlays that float over everything |
| `workbench` | the VS Code editor (code-server) | activity bar, tabs, the "Claude Code: Open" button |
| `wiki` | the wiki panel iframe | wiki DOM |
| `claude` | the Claude Code chat **webview** (only exists while the panel is open) | the chat input + send button |
## How it runs on Linux: the frame bus
WebKitGTK has no Chrome DevTools Protocol. Hydrogen injects an agent script into every frame,
in an **isolated script world**, and `/eval-in` sends your JS to the frame you name over that
bus (`hydrogen-app/src/linux_frame_bus.rs`). What that means for you:
- **The DOM is shared, page JS globals are not.** `document.querySelector`, events, `click()`,
`execCommand`, styles and IndexedDB all work. A page's own globals (Svelte stores, a
`window.__something` the page defined) are invisible: drive the DOM, not the page's functions.
- **Context ids are the agent's random ids**, stable for the frame's life. Don't keep them
across reloads.
- **No surface list:** `GET /targets` and a `/eval-in` call without `js` return nothing on
Linux. A miss returns an error that names every candidate frame, which is the discovery.
- Same-origin child frames without their own agent (VS Code webview content) are reached
through their parent's agent, so the Claude chat is still `target:"claude"`.
## Reaching the control API
The workspace shares the host's network, so the API is on `127.0.0.1`. Read the live URL from
the discovery file:
```bash
BASE="$(cat ~/.adom/hydrogen-control-url)" # http://127.0.0.1:<dynamic>
```
(Never hardcode the port — read the live URL from `~/.adom/hydrogen-control-url`.)
## The call
```
POST /eval-in
{
"target": "shell" | "workbench" | "wiki" | "claude" | "<url-substring>" | "<id>",
"js": "<javascript; value of last expression is returned>",
"find": "<OPTIONAL JS expression>", // disambiguate among same-origin contexts
"frame": "<url-substring | index>", // OPTIONAL nested-context selector
}
→ { "ok": true, "value": <result>, "target": "<matched url>", "contextId": N, "frames": [...] }
```
A returned promise is always awaited on Linux.
### `find` — the important one
The workbench has several same-origin frames. Origin alone is ambiguous, so pass `find`:
a JS **expression** (e.g. `document.querySelector('...')`, NOT a bare CSS selector).
`/eval-in` evals it in each candidate context and runs your `js` in the **first
one where `find` is truthy**.
## Recipes
### Add-on: a widget in the top nav (e.g. a usage meter) — target `shell`
Inject once; it persists until reload. Append your element to `nav` in the shell.
### Demo overlay: a red arrow over everything that you reposition — target `shell`
Inject a `position:fixed; z-index:2147483647; pointer-events:none` element with a
CSS `transition` into the shell `body`, then move it with cheap follow-up evals
(it glides). The shell floats over all iframes, so window coords work everywhere.
### Highlight an element (even deep in the workbench / Claude webview)
Eval **inside the element's own surface** and set `outline` — no coordinate math.
Use `find` to land in the right context, e.g.
`find: document.querySelector("a[aria-label='Claude Code: Open']")`.
### Type into & submit the Claude chat (panel must be open)
Stable selectors (NOT the CSS-module hash classes like `.messageInput_xxxx`,
which change per build):
- input = `[aria-label='Message input']` (a `contenteditable` div) — focus it,
then `document.execCommand('insertText', false, text)`.
- submit = `button[type='submit'][data-permission-mode]` (disabled until text) —
`.click()` it; fallback = dispatch an `Enter` keydown on the input.
Prefer the `/claude/inject` endpoints for this (see **hydrogen-claude-management**).
## Verify-then-fallback (recommended)
`/eval-in` returns the JS value, so always verify: after an action, eval a probe
and check it; if it fails, try a second technique.
## Don'ts
- Don't hardcode the control port — read `/ports`.
- Don't pass `find` as a bare CSS selector — it's a JS expression.
- Don't select by CSS-module hash classes — use stable attributes (`aria-label`, `data-*`, `role`).
- Don't expect the `claude` webview to exist unless the Claude panel is open.
- Don't use `/eval` for workbench/Claude — it only reaches the shell page.
- `/iframe-eval` is CDP-only and does nothing useful on Linux.
- Don't call page globals: the isolated world cannot see them.
## Cross-references
- **hydrogen-api** — the full control API surface
- **hydrogen-ui** / **hydrogen-adom-menu** — where UI elements live
- **hydrogen-self-screenshot** — capture the result of your injection
## Recipe: hide/show activity-bar icons (the RIGHT way — persisted, overflow-proof)
Do NOT hide activity-bar icons with `display:none` on `.action-item` — that misses
icons collapsed into the "…" (Additional Views) **overflow** and doesn't persist.
Instead write VS Code's own source-of-truth state, then reload the workbench:
- **DB:** `vscode-web-state-db-global` → store `ItemTable` → key `workbench.activity.pinnedViewlets2`
- It's an array of `{id, pinned, visible, order}`. Set **`pinned:false` to hide** an
icon from the activity bar (works even if it's in the overflow), **`pinned:true` to restore**.
- **IDs:** Explorer `workbench.view.explorer` · Search `workbench.view.search` ·
Source Control `workbench.view.scm` · Run&Debug `workbench.view.debug` ·
Extensions `workbench.view.extensions` (extension views: `workbench.view.extension.<id>`).
- IndexedDB is **per-origin**, so read/write from **any** `localhost:7380` context
(target `workbench`, `find: "(typeof indexedDB!=='undefined')"`) — don't require the
workbench main doc (it's absent during a reload).
- After writing, **reload the workbench** (`iframe.src=iframe.src` on the `shell`, or
`POST /reload-vscode`) so VS Code re-reads `pinnedViewlets2`.
```jsonc
// hide Search / Source Control / Run&Debug (then reload)
{ "target":"workbench", "find":"(typeof indexedDB!=='undefined')", "awaitPromise":true,
"js":"(async function(){function g(d,k){return new Promise(function(r){var o=indexedDB.open(d);o.onsuccess=function(){var b=o.result;var q=b.transaction('ItemTable','readonly').objectStore('ItemTable').get(k);q.onsuccess=function(){b.close();r(q.result)}}})}function p(d,k,v){return new Promise(function(r){var o=indexedDB.open(d);o.onsuccess=function(){var b=o.result;var t=b.transaction('ItemTable','readwrite');t.objectStore('ItemTable').put(v,k);t.oncomplete=function(){b.close();r(true)}}})}var DB='vscode-web-state-db-global',K='workbench.activity.pinnedViewlets2';var a=JSON.parse(await g(DB,K));var ids=['workbench.view.search','workbench.view.scm','workbench.view.debug'];a.forEach(function(e){if(ids.indexOf(e.id)>-1)e.pinned=false});await p(DB,K,JSON.stringify(a));return 'hidden';})()" }
```
`POST /vscode/hide-activity-items` does the same job server-side.