Overview Files Skills Packages Releases Dependencies Issues1 Breadcrumbs Pull Requests Activity

name: hd-overview description: > Master index for all Hydrogen Desktop skills. Start here to find the right skill for any HD topic. Skills are split into a runtime-neutral "shared" set plus a runtime-specific set (WSL2 by default, Docker as legacy fallback). Trigger words: HD skills, hydrogen desktop, what skills, find skill, HD help, HD overview, skill index, HD reference.

Hydrogen Desktop — Skill Index

Hydrogen Desktop (HD) is Adom's standalone Tauri v2 app that runs the full Hydrogen experience locally. One exe manages your workspace, VS Code, Claude Code, the bridges, and the Adom Wiki — zero cloud dependency.

⚠️ First: know your runtime — `hd-runtime-mode`

HD hosts your workspace one of two ways: a WSL2 Ubuntu distro Adom-Workspace (the default) or a Docker container (legacy, HD_RUNTIME=docker). Almost every fact below — container vs distro, files, ports, stats, setup steps — depends on which is active. Read hd-runtime-mode first to confirm your runtime, then use the matching runtime-specific skill. HD only installs the skills for the active runtime, so in a given workspace you'll usually have exactly the right set.

Shared skills (runtime-neutral — always installed)

Skill	What it covers
hd-runtime-mode	WSL2 vs Docker runtime: how to tell which you're in and what differs. Read first.
hd-golden-image	Your workspace is a pre-baked golden WSL2 image — gallia, the CLIs, claude, code-server, settings, and these skills are baked in (not installed by setup steps); how updates work. Lightweight by design: tools like ffmpeg/imagemagick aren't baked — install on demand (`sudo apt-get install`) rather than refusing.
hd-skill-loop	(Maintainers) The loop to fix a wrong/stale HD skill: verify vs the live HD, fix it live, write it back to the repo, bake it into the next image.
hd-who-am-i	Answer "who am I / what can I do here" — identity, resources, environment intro.
hd-adom-auth	Adom login/logout, session token, profile menu, how auth feeds setup.
hd-claude-auth	How Claude Code signs in: OAuth via Browser Picker, credential backup, the `claude-auth` step.
hd-api	Control API reference (`127.0.0.1:47084`). Runtime-neutral endpoints + runtime-specific notes.
hd-desktop-sse	Local workspace API + SSE — how adom-cli inside the workspace controls HD (replaces Carbon locally).
hd-monitor	Real-time SSE event stream + Monitor-tool patterns for watching workspace mutations.
hd-ui	HD's UI: menus, dialogs, panels, CDP-driven navigation, brand/CSS conventions.
hd-open-url	The decision guide for "open a website" — the six ways (webview tab, HD window, Pup, native browser, picker, headless curl) and when to pick each.
hd-browser-picker	URL interception — every link routes through the Browser Profile Dialog.
hd-permissions	Why mic/camera/clipboard/notifications "just work" in HD — WebView2 permissions are auto-granted, so webview apps see no Allow prompts.
hd-tab-icons	Webview tab icon system — `displayIcon`, icon resolution, SVG data URLs.
hd-profile-menu	The avatar dropdown: profile/repos/molecules links and logout.
hd-adom-desktop	What HD and Adom Desktop (AD) are and how they work together — AD is your hands on the user's real OS (files, shell, OS screenshots, app launch, bridges).
hd-bridges	Built-in KiCad/Fusion/Puppeteer bridges + extensible wiki catalog (e.g. Blender) + AD capability list.
hd-eval	Inject JS into any HD surface (shell/workbench/wiki/Claude) via /eval-in — add-ons, overlays, highlights, drive UI.
hd-adom-menu	The upper-left Adom logo menu (Settings, Ports, API Explorer, DevTools, Setup/Virgin Reset) + About dialog + version readout.
hd-settings	HD's Settings dialog + the full preferences tree (theme, vim mode, 3D control style, launch-on-boot, AD window behavior).
hd-file-transfer	Move files both ways between the WSL2 workspace and the Windows PC.
hd-embedded-ad	HD ↔ Adom Desktop embedded mode: the tray, why AD is hidden, the footer pill.
hd-self-screenshot	How the AI screenshots HD panels + any host window (window control, multi-monitor), injects to shotlog, runs visual self-checks.
hd-capture-share	The screen-share + "AI wants access" approval + countdown the AI triggers to capture the editor; tab/screen scopes, Webview/Pup window mode.
hd-recording	Record the screen/mic — the in-app `.webm` recorder (→ `recordings/`) and AD desktop recording, with the tab-vs-desktop footgun.
hd-notifications	Reach the user outside the window — native Windows toasts + emergency taskbar flash via `notify_user`.
hd-captions	Paint labeled text on the user's screen — a Win32 always-on-top caption overlay for demos / step callouts.
hd-welcome	The static welcome page shown after setup completes.
hd-self-update	How HD updates itself: the "Restart to update (vX→vY)" banner (UpdateBanner.svelte) plus the AI-first update path.
hd-staying-current	How workspace skills/packages stay current — registry-native updates (`adom-wiki pkg update` + `adom/hook`); the old workspace-updater daemon is retired.
hd-skill-catalog	The catalog of skills your Claude has in this workspace.
hd-overview	This index.

Runtime-specific skills (you get the WSL2 or the Docker variant)

These topics exist in two parallel implementations — wsl2/ (default) and docker/ (legacy) — with the same skill names. Trust the one for your active runtime (see hd-runtime-mode).

Skill	What it covers
hd-container	Context for Claude running inside the workspace: relay, direct connect, bridge commands, env vars.
hd-topology	The three-layer architecture and how to reach the workspace (WSL2: `wsl -d Adom-Workspace`; Docker: `docker exec`).
hd-networking	Port architecture, host access (`127.0.0.1` / mirrored networking), code-server proxy. Canonical port behavior.
hd-ports	Forwarding workspace services to Windows (WSL2 auto-forward vs Docker `-p` + `/proxy/`).
hd-port-watcher	The dynamic port-forward daemon for extension OAuth callbacks.
hd-volume	Where your files live, what persists, how to copy out, what a reset wipes.
hd-container-stats	The title-bar CPU/RAM "Container" indicator and how its stats are gathered.
hd-setup	The setup panel, Run All, Rollback, Virgin Reset.
hd-setup-steps	What each setup step did to prepare your workspace.

WSL2-only

Skill	What it covers
hd-workspace-lifecycle	WSL distro lifecycle: import/export/terminate/unregister, code-server as an HD-owned child, the never-global-WSL rule.
hd-workspace-monitoring	Distro + code-server health monitoring, floaty states, the 15s poll, auto-start.

Docker-only (legacy `HD_RUNTIME=docker`)

Skill	What it covers
hd-docker-desktop	Silently install/upgrade/start/monitor Docker Desktop as invisible infrastructure.
hd-docker-lifecycle	Docker Desktop + container lifecycle: WSL2 recovery, restart/stop rules, health checks.
hd-docker-monitoring	Frontend monitoring of the Docker container and Docker Desktop.

---
name: hd-overview
description: >
  Master index for all Hydrogen Desktop skills. Start here to find the right
  skill for any HD topic. Skills are split into a runtime-neutral "shared" set
  plus a runtime-specific set (WSL2 by default, Docker as legacy fallback).
  Trigger words: HD skills, hydrogen desktop, what skills, find skill, HD help,
  HD overview, skill index, HD reference.
---

# Hydrogen Desktop — Skill Index

Hydrogen Desktop (HD) is Adom's standalone Tauri v2 app that runs the full
Hydrogen experience locally. One exe manages your workspace, VS Code,
Claude Code, the bridges, and the Adom Wiki — zero cloud dependency.

## ⚠️ First: know your runtime — **`hd-runtime-mode`**

HD hosts your workspace one of two ways: a **WSL2 Ubuntu distro `Adom-Workspace`**
(the default) or a **Docker container** (legacy, `HD_RUNTIME=docker`). Almost every
fact below — container vs distro, files, ports, stats, setup steps — depends on
which is active. **Read `hd-runtime-mode` first** to confirm your runtime, then use
the matching runtime-specific skill. HD only installs the skills for the active
runtime, so in a given workspace you'll usually have exactly the right set.

## Shared skills (runtime-neutral — always installed)

| Skill | What it covers |
|---|---|
| **hd-runtime-mode** | WSL2 vs Docker runtime: how to tell which you're in and what differs. Read first. |
| **hd-golden-image** | Your workspace is a pre-baked golden WSL2 image — gallia, the CLIs, claude, code-server, settings, and these skills are baked in (not installed by setup steps); how updates work. **Lightweight by design: tools like ffmpeg/imagemagick aren't baked — install on demand (`sudo apt-get install`) rather than refusing.** |
| **hd-skill-loop** | (Maintainers) The loop to fix a wrong/stale HD skill: verify vs the live HD, fix it live, write it back to the repo, bake it into the next image. |
| **hd-who-am-i** | Answer "who am I / what can I do here" — identity, resources, environment intro. |
| **hd-adom-auth** | Adom login/logout, session token, profile menu, how auth feeds setup. |
| **hd-claude-auth** | How Claude Code signs in: OAuth via Browser Picker, credential backup, the `claude-auth` step. |
| **hd-api** | Control API reference (`127.0.0.1:47084`). Runtime-neutral endpoints + runtime-specific notes. |
| **hd-desktop-sse** | Local workspace API + SSE — how adom-cli inside the workspace controls HD (replaces Carbon locally). |
| **hd-monitor** | Real-time SSE event stream + Monitor-tool patterns for watching workspace mutations. |
| **hd-ui** | HD's UI: menus, dialogs, panels, CDP-driven navigation, brand/CSS conventions. |
| **hd-open-url** | The decision guide for "open a website" — the six ways (webview tab, HD window, Pup, native browser, picker, headless curl) and when to pick each. |
| **hd-browser-picker** | URL interception — every link routes through the Browser Profile Dialog. |
| **hd-permissions** | Why mic/camera/clipboard/notifications "just work" in HD — WebView2 permissions are auto-granted, so webview apps see no Allow prompts. |
| **hd-tab-icons** | Webview tab icon system — `displayIcon`, icon resolution, SVG data URLs. |
| **hd-profile-menu** | The avatar dropdown: profile/repos/molecules links and logout. |
| **hd-adom-desktop** | What HD and Adom Desktop (AD) are and how they work together — AD is your hands on the user's real OS (files, shell, OS screenshots, app launch, bridges). |
| **hd-bridges** | Built-in KiCad/Fusion/Puppeteer bridges + extensible wiki catalog (e.g. Blender) + AD capability list. |
| **hd-eval** | Inject JS into any HD surface (shell/workbench/wiki/Claude) via /eval-in — add-ons, overlays, highlights, drive UI. |
| **hd-adom-menu** | The upper-left Adom logo menu (Settings, Ports, API Explorer, DevTools, Setup/Virgin Reset) + About dialog + version readout. |
| **hd-settings** | HD's Settings dialog + the full preferences tree (theme, vim mode, 3D control style, launch-on-boot, AD window behavior). |
| **hd-file-transfer** | Move files both ways between the WSL2 workspace and the Windows PC. |
| **hd-embedded-ad** | HD ↔ Adom Desktop embedded mode: the tray, why AD is hidden, the footer pill. |
| **hd-self-screenshot** | How the AI screenshots HD panels + any host window (window control, multi-monitor), injects to shotlog, runs visual self-checks. |
| **hd-capture-share** | The screen-share + "AI wants access" approval + countdown the AI triggers to capture the editor; tab/screen scopes, Webview/Pup window mode. |
| **hd-recording** | Record the screen/mic — the in-app `.webm` recorder (→ `recordings/`) and AD desktop recording, with the tab-vs-desktop footgun. |
| **hd-notifications** | Reach the user outside the window — native Windows toasts + emergency taskbar flash via `notify_user`. |
| **hd-captions** | Paint labeled text on the user's screen — a Win32 always-on-top caption overlay for demos / step callouts. |
| **hd-welcome** | The static welcome page shown after setup completes. |
| **hd-self-update** | How HD updates itself: the "Restart to update (vX→vY)" banner (UpdateBanner.svelte) plus the AI-first update path. |
| **hd-staying-current** | How workspace skills/packages stay current — registry-native updates (`adom-wiki pkg update` + `adom/hook`); the old workspace-updater daemon is retired. |
| **hd-skill-catalog** | The catalog of skills your Claude has in this workspace. |
| **hd-overview** | This index. |

## Runtime-specific skills (you get the WSL2 *or* the Docker variant)

These topics exist in two parallel implementations — `wsl2/` (default) and
`docker/` (legacy) — with the same skill names. Trust the one for your active
runtime (see `hd-runtime-mode`).

| Skill | What it covers |
|---|---|
| **hd-container** | Context for Claude running inside the workspace: relay, direct connect, bridge commands, env vars. |
| **hd-topology** | The three-layer architecture and how to reach the workspace (WSL2: `wsl -d Adom-Workspace`; Docker: `docker exec`). |
| **hd-networking** | Port architecture, host access (`127.0.0.1` / mirrored networking), code-server proxy. Canonical port behavior. |
| **hd-ports** | Forwarding workspace services to Windows (WSL2 auto-forward vs Docker `-p` + `/proxy/`). |
| **hd-port-watcher** | The dynamic port-forward daemon for extension OAuth callbacks. |
| **hd-volume** | Where your files live, what persists, how to copy out, what a reset wipes. |
| **hd-container-stats** | The title-bar CPU/RAM "Container" indicator and how its stats are gathered. |
| **hd-setup** | The setup panel, Run All, Rollback, Virgin Reset. |
| **hd-setup-steps** | What each setup step did to prepare your workspace. |

### WSL2-only
| Skill | What it covers |
|---|---|
| **hd-workspace-lifecycle** | WSL distro lifecycle: import/export/terminate/unregister, code-server as an HD-owned child, the never-global-WSL rule. |
| **hd-workspace-monitoring** | Distro + code-server health monitoring, floaty states, the 15s poll, auto-start. |

### Docker-only (legacy `HD_RUNTIME=docker`)
| Skill | What it covers |
|---|---|
| **hd-docker-desktop** | Silently install/upgrade/start/monitor Docker Desktop as invisible infrastructure. |
| **hd-docker-lifecycle** | Docker Desktop + container lifecycle: WSL2 recovery, restart/stop rules, health checks. |
| **hd-docker-monitoring** | Frontend monitoring of the Docker container and Docker Desktop. |

Hydrogen Desktop Bootstrap (apps + skills)