Inspecting the live Hermes desktop DOM
Overview
When you are developing
and the user is running that same app
(
/
), you can read the
live rendered DOM of the window
they are looking at — computed styles, geometry, which CSS rule actually won,
console output — instead of inferring it from
and being wrong.
Dev-server runs open a Chrome DevTools Protocol port on
automatically. The renderer is a Chromium page, so everything DevTools can read,
a script can read.
This does not replace looking at it. CDP answers factual questions ("what
is the computed padding", "did this element render", "which selector matches").
It cannot tell you whether the result looks good. Colour balance, spacing feel,
and "is this ugly" still need the user's eyes or a screenshot. Answer facts with
CDP; hand aesthetics to the user.
When to Use
- Verifying a UI change actually took effect in the running app
- "Why is this element still X?" — find the winning rule before editing anything
- Locating a stable selector for a component you're about to change
- Checking a design token's computed value on a real node
- Reading renderer console errors the user mentions but can't copy out
Don't use for: perf profiling or heap work (
,
), or anything where the real question is "does this
look right".
The port
Open on
for any dev-server run. Closed in exactly two cases
(
apps/desktop/electron/dev-cdp.ts
):
- packaged builds — always, and no environment value overrides it;
- no
HERMES_DESKTOP_DEV_SERVER
moves the port (
) or disables it (
).
Check before doing anything else:
bash
curl -s --max-time 3 http://127.0.0.1:${HERMES_DESKTOP_CDP_PORT:-9222}/json/version
Empty → no port. Do not guess another port silently.
Never relaunch the user's app to get a port. That destroys their session and
their state. Launch your own isolated instance instead (below).
Reading the DOM
apps/desktop/scripts/eval.mjs
is the one-liner:
bash
cd apps/desktop
node scripts/eval.mjs "document.querySelectorAll('[data-slot]').length"
For multi-step work use the shared client — it has target discovery and
promise-aware eval:
js
import { CDP, SELECTORS } from './scripts/perf/lib/cdp.mjs'
const cdp = await CDP.connect({ port: 9222, match: '5174' })
const out = await cdp.eval(`JSON.stringify({
radius: getComputedStyle(document.documentElement).getPropertyValue('--radius-scalar').trim(),
composer: !!document.querySelector('[data-slot="composer-rich-input"]')
})`)
cdp.close()
in
holds the stable
hooks
(composer, thread viewport, assistant message, turn pair, profile rail). Prefer
them over inventing a
— they are updated as a unit when
components move.
The question this is best at: which rule won?
Editing every call site because a style "isn't applying" is the classic waste.
Read the real node first:
js
const el = document.querySelector('[data-slot="aui_assistant-message-root"] a')
JSON.stringify({
ownClasses: el.className,
weight: getComputedStyle(el).fontWeight,
parents: (() => {
const out = []
let n = el
while ((n = n.parentElement) && out.length < 6) out.push(n.className)
return out
})()
})
If the node carries no class of its own, the value is
inherited — sweeping
call sites will not fix it, and you need the ancestor rule. A plugin stylesheet
(e.g.
's
prose a { font-weight: 500 }
) routinely beats
a utility class; override on the shared class, not at each usage.
Your own isolated instance
When there is no port, or you must not disturb the user's window:
bash
cd apps/desktop
HERMES_HOME=/tmp/cdp-probe-home \
HERMES_DESKTOP_DEV_SERVER=http://127.0.0.1:5174 \
HERMES_DESKTOP_CDP_PORT=9333 \
npx electron . --user-data-dir=/tmp/cdp-probe-userdata
The separate
dodges Electron's single-instance lock, so it
cannot collide with a running
; the separate
keeps it away
from real sessions. Pick a port other than 9222 for the same reason. Run it in
the background and kill it when done.
does the same with a temp
baked in, if you
also want the perf harness.
Pitfalls
- Never kill the user's dev server or app to "free" anything. A mid-serve
kill nukes Chromium's socket pool, and the resulting
gets blamed on whatever you just changed.
- A throwaway has no backend. The app logs for
and may exit on its own. The renderer still mounts and the DOM is
readable — read promptly, and don't mistake a self-exited probe for a broken
port. Chromium logs
DevTools listening on ws://127.0.0.1:<port>/…
- Poll, don't probe once. A just-launched app needs a second or two before
the port answers.
- Never dump the whole DOM. The desktop renders hundreds of nodes and
will bury your context. Project down to a small JSON object inside
the evaluated expression.
- Pass to . Without it you may attach to the pet
overlay, quick-entry window, or a devtools target instead of the main window.
- returns the value; raw double-nests it
(). Use the wrapper.
- is under in this repo. The note in
apps/desktop/scripts/profile-typing-lag.md