feat(desktop): let the agent inspect the desktop app it's developing

[OutThisLife]

Hermes develops Hermes Desktop but cannot see it. UI questions — did that change take effect, why is this element still the wrong colour, what does this token compute to — get answered by reading .tsx and inferring, or by asking the user to look. The renderer is a Chromium page; it was one command-line switch away from being readable.

How it works

The switch. app.commandLine.appendSwitch('remote-debugging-port', N) makes Chromium start a debugging server. It has to be set at module scope (main.ts:280) — Chromium parses its command line during init, which happens between module evaluation and app.whenReady() (line 11378). Appending the switch inside the ready handler is a silent no-op. That's why this sits with the GPU/compositing switches rather than anywhere more obvious.

What the port serves. GET /json/list enumerates every debuggable target (each BrowserWindow, plus devtools windows) with a webSocketDebuggerUrl. Open that socket and you're speaking CDP: Runtime.evaluate for expressions, DOM/CSS for structure and computed styles, Input.dispatchKeyEvent for synthetic input. scripts/perf/lib/cdp.mjs already wraps all of it — request/response correlation by id, event listeners, promise-aware eval.

Why 9222. 24 scripts under scripts/ already hardcode or default to it. Matching that default is what makes the toolkit work with zero configuration rather than needing every script touched.

Target selection matters. A running desktop has several page targets — main window, pet overlay (?win=overlay), quick entry (?win=quick). CDP.connect({ match: '5174' }) filters on the dev-server URL to get the main window; without match you attach to whichever target enumerates first.

How the gate works

electron/dev-cdp.ts is a pure function over { env, isPackaged, devServer }. Pure because the alternative is testing a gate by launching Electron, which is slow enough that nobody does it, and the packaged branch is the one that must never regress.

Packaged is checked first, and it's stronger than it looks:

const IS_PACKAGED = app.isPackaged || Boolean(process.env.HERMES_DESKTOP_IS_PACKAGED)

scripts/bundle-electron-main.mjs esbuild-defines process.env.HERMES_DESKTOP_IS_PACKAGED to the literal true for every non---dev bundle. So in a production bundle that expression is constant-folded at build time — the packaged check isn't reading the environment, it's a baked-in true that survives an unpackaged electron . against dist/. Setting the env var can only ever turn the gate on, never off.

The dev-server check is the second discriminator. HERMES_DESKTOP_DEV_SERVER is only set by npm run dev / hgui, so its presence distinguishes a source-tree run from a dist/-loading one. The dist/ case is how the packaged app gets smoke tested, so it should behave like the packaged app.

Everything else opens on 9222. HERMES_DESKTOP_CDP_PORT is an override — a different port, or off/0/false/no. Out-of-range and non-integer values are refused rather than silently coerced (Number('92 22') is NaN, but Number('') is 0, which is why the empty case is handled before the numeric parse).

Refusals log only when they contradict something explicitly requested — a typo'd port, an explicit off. Packaged and dist/ runs are closed by design and stay quiet, because a warning on every packaged launch is noise nobody can act on.

Why on by default

A dev server already executes arbitrary local JS: vite's module graph, every postinstall in node_modules. A loopback CDP port doesn't widen that, and perf:serve has opened one unconditionally since it was written. The address is pinned to 127.0.0.1 explicitly rather than relying on Chromium's default, and isn't configurable — off-host renderer debugging has no use case here, and the knob would only invite someone to try.

The skill

skills/software-development/inspecting-hermes-desktop-dom — the port is useless if the agent doesn't know it exists. Sits beside node-inspect-debugger, which covers the same protocol for Node/perf; this is the DOM/CSS half.

The load-bearing content is what goes wrong:

• Never relaunch or kill the user's app to get a port. A mid-serve kill nukes Chromium's socket pool; the resulting ERR_NETWORK_CHANGED gets blamed on whatever was edited last. Launch an isolated instance (--user-data-dir dodges the single-instance lock, separate HERMES_HOME keeps it off real sessions).
• Never dump the whole DOM. Hundreds of nodes; project down to a small JSON object inside the evaluated expression.
• "Which rule won?" — read getComputedStyle on the real node and walk ancestors before editing call sites. No class on the node means the value is inherited and sweeping usages won't fix it.
• A throwaway HERMES_HOME has no backend, so a probe instance logs ECONNREFUSED and can exit on its own. Chromium's DevTools listening on ws://… line is the proof the port bound; don't read a self-exited probe as a broken gate. (Hit this during verification.)
• CDP answers factual questions, not aesthetic ones. Renders-or-not is a fact. Looks-right is the user's call.

Also

scripts/eval.mjs hardcoded :9222 and threw a raw ECONNREFUSED stack when nothing was listening. Honours the override now, falls back to any page target when the dev-port match misses, and explains itself on failure.

Verification

Gate: 11 unit tests (vitest run --project electron electron/dev-cdp.test.ts). Skill frontmatter run through the repo's own _validate_frontmatter + extract_skill_description — first draft truncated at the 57-char index budget and lost its trigger word, so it was shortened; tests/tools/test_skill_manager_tool.py 129 passed.

Runtime, real Electron, isolated --user-data-dir + HERMES_HOME so a live hgui was never touched:

run	result
dev server, no env var	DevTools listening on ws://127.0.0.1:9222/…; lsof shows TCP 127.0.0.1:9222 (LISTEN) — loopback, not *:9222; scripts/eval.mjs returned {"title":"Hermes","nodes":216}
HERMES_DESKTOP_CDP_PORT=off	closed; logged renderer debugging disabled by HERMES_DESKTOP_CDP_PORT.
HERMES_DESKTOP_IS_PACKAGED=1 + =9222	closed, silent — no DevTools listening, nothing bound

tsc --build tsconfig.electron.json and eslint clean. 413 insertions, 2 deletions across 6 files.

[github-actions]

૮ >ﻌ< ა ci review

_{ran on d76d083}

ℹ️ Info

Desktop E2E visual evidence · View test artifacts · View job

1 visual diff.

_{inline evidence upload failed.}

Failed to upload diff-665a0833239e-onboarding-overlay-diff.png with gh image (exit code 1): Error uploading /home/runner/work/_temp/e2e-evidence/diff-665a0833239e-onboarding-overlay-diff.png: step 0 (get upload token): uploadToken not found on repo page — do you have write access to NousResearch/hermes-agent? (or, if NousResearch enforces SAML SSO, authorize at https://github.com/orgs/NousResearch/sso)