Skip to main content
skill CX Codex

inspecting-hermes-desktop-dom — Claude Code skill for live DOM

The inspecting-hermes-desktop-dom skill reads the live DOM, computed CSS, and console output from Hermes Desktop over CDP. Use it to check whether a UI change took effect or identify the style rule in control.

MIT 263 installs ★ 265,216 updated 2026-11-10

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add NousResearch/hermes-agent --skill inspecting-hermes-desktop-dom -a claude-code
Open on GitHub

What inspecting-hermes-desktop-dom does

The skill connects to the Chromium window in apps/desktop through the Chrome DevTools Protocol. It can inspect rendered elements, computed styles, geometry, and renderer console messages. For a quick check it uses apps/desktop/scripts/eval.mjs; multi-step inspection can use the shared CDP client to find the right window and run JavaScript.

A dev-server run exposes CDP at 127.0.0.1:9222; packaged builds keep the port closed. The skill also describes launching a separate Electron instance with its own HERMES_HOME, port, and --user-data-dir. Do not restart the user's app to open CDP: that would end their session.

It can help trace inherited styles or a plugin rule that overrides a CSS class. It cannot judge whether the interface looks good, and it is not meant for performance profiling.

What it helps with

  • confirm a UI change rendered in the running app
  • find the CSS rule setting an element's computed style
  • check a design token on a rendered node
  • read renderer console errors
  • choose a stable data-slot selector

Example prompts for the agent

  • Use CDP to check whether the style change reached this element.
  • Find the rule setting fontWeight on a link in an assistant message.
  • Read the console errors from the running apps/desktop window.

How to install inspecting-hermes-desktop-dom

1Skills CLI (Vercel)

npx skills add NousResearch/hermes-agent --skill inspecting-hermes-desktop-dom -a claude-code

2Manually: put the files in place

~/.claude/skills/inspecting-hermes-desktop-dom/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/inspecting-hermes-desktop-dom/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about inspecting-hermes-desktop-dom

How do I install inspecting-hermes-desktop-dom in Claude Code?

Run npx skills add NousResearch/hermes-agent --skill inspecting-hermes-desktop-dom -a claude-code. The skill file is at ~/.claude/skills/inspecting-hermes-desktop-dom/SKILL.md.

What does inspecting-hermes-desktop-dom do?

It uses CDP to inspect the live Hermes Desktop DOM, computed styles, and renderer console output. That can show which CSS rule is affecting an element.

When is the Hermes Desktop CDP port closed?

Packaged builds keep it closed, as does running electron . without HERMES_DESKTOP_DEV_SERVER. The skill describes starting a separate Electron instance with its own port and data directory.

Source text

SKILL.md · MIT
---
name: inspecting-hermes-desktop-dom
description: "Read the live Hermes desktop DOM/CSS over CDP."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [desktop, electron, cdp, dom, ui-verification, self-inspection]
    related_skills: [node-inspect-debugger, systematic-debugging, dogfood]
---

# Inspecting the live Hermes desktop DOM

## Overview

When you are developing `apps/desktop` and the user is running that same app
(`hgui` / `pnpm run dev`), 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 `.tsx` and being wrong.

Dev-server runs open a Chrome DevTools Protocol port on `127.0.0.1:9222`
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 (`node-inspect-debugger`,
`debugging-hermes-desktop`), or anything where the real question is "does this
look right".

## The port

Open on `127.0.0.1:9222` 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`** — an unpackaged `electron .` against
  `dist/` is how the packaged app gets smoke tested, so it behaves like one.

`HERMES_DESKTOP_CDP_PORT` moves the port (`=9333`) or disables it (`=off`).

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()
```

`SELECTORS` in `scripts/perf/lib/cdp.mjs` holds the stable `data-slot` hooks
(composer, thread viewport, assistant message, turn pair, profile rail). Prefer
them over inventing a `querySelector` — 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. `@tailwindcss/typography`'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=$HOME/.hermes/cache/scratch/cdp-probe-home \
HERMES_DESKTOP_DEV_SERVER=http://127.0.0.1:5174 \
HERMES_DESKTOP_CDP_PORT=9333 \
  pnpm exec electron . --user-data-dir=$HOME/.hermes/cache/scratch/cdp-probe-userdata
```

The separate `--user-data-dir` dodges Electron's single-instance lock, so it
cannot collide with a running `hgui`; the separate `HERMES_HOME` 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.

`pnpm run perf:serve` does the same with a temp `HERMES_HOME` 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 `ERR_NETWORK_CHANGED`
  gets blamed on whatever you just changed.
- **A throwaway `HERMES_HOME` has no backend.** The app logs `ECONNREFUSED` for
  `hermes:api` 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>/…` when it
  binds; that line is the proof the port opened.
- **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
  `outerHTML` will bury your context. Project down to a small JSON object inside
  the evaluated expression.
- **Pass `match` to `CDP.connect`.** Without it you may attach to the pet
  overlay, quick-entry window, or a devtools target instead of the main window.
- **`cdp.eval` returns the value; raw `Runtime.evaluate` double-nests it**
  (`.result.result.value`). Use the wrapper.
- **`import.meta.env.DEV` is `true` under `vite dev`** in this repo. The note in
  `apps/desktop/scripts/profile-typing-lag.md` claiming otherwise is stale.

© Hermes Agent · MIT · NousResearch/hermes-agent

Similar skills

All skills for Frontend and UI →

From the same set61

The whole set →
grounded-citations grounded-citations grounds LLM responses in verifiable sources using Perplexity-style bracketed citations and strict quotation checks via an external ledger. CX Codex +1 307installs openhue Controls Philips Hue lights, rooms, and scenes via OpenHue CLI. Useful for adjusting lighting and triggering presets directly from the terminal. CX Codex +1 288installs pdf A skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that handles PDF files end to end: build from specs, extract tables, fill forms, merge pages, encrypt. CX Codex +1 283installs polymarket Pulls Polymarket data through its public REST APIs: markets, prices, orderbooks and history. Use it when you want the odds the market gives some event. CX Codex +1 282installs github Routes GitHub workflows through the gh CLI, covering issues, PR lifecycles, code reviews, and repo tasks. Designed for tracking delivery straight from the terminal. CX Codex +1 245installs heartmula This skill guides local song creation with HeartMuLa from lyrics and tags. Use it when you want an open-source workflow for AI music generation. CX Codex +1 230installs godmode godmode is a Claude Code skill with three prompt-level routes past model safety filters: templates, word obfuscation, and querying a model pool through OpenRouter. CX Codex +1 214installs competitor-news-monitor competitor-news-monitor — a skill that watches a fixed list of companies and sends a digest of material news, with primary-source links behind each item. CX Codex +1 204installs

Project sponsors

Companies that keep this analytics open