Adom Hydrogen (Windows / WSL2)

Windows companion to hydrogen-adom-auth: the %APPDATA% paths of Hydrogen's session and Claude credential files, and how to read the injected Adom API key from outside the distro. Use when asked where is the session token on windows or for hydrogen-session.txt.

Triage Adom Bridge (ab) when a Hydrogen workspace cannot reach it, including ab crashing on boot after a bad release: crash.log first, out-of-band checks, reinstall. Use when ab won't connect, no desktop client connected, ab never starts, or the bridge keeps dying.

Open and drive AI conversations in Hydrogen from code over the control API: open a thread, list open ones, put text in a chat box, send a prompt and confirm it landed, reopen or close. Use when asked to open a new claude/codex thread, send a prompt to an AI, or list open AI conversations.

The AI Threads panel in Hydrogen: the live tree of open AI conversations (Claude, Codex, Kimi), reorder, rename, tag, TUI threads, and the beta on-startup setting. Use when asked about ai threads, my ai conversations, which ai is running, rename a thread, or a tui thread.

Hydrogen's Annotate tool: the Title Bar pencil or Win+Alt+A lets the user draw on the whole screen (circle, arrow, box, note, snip) and puts a PNG on the clipboard for the AI thread. Use when asked to annotate, circle it, mark up the screen, snip a region, or about POST /annotate.

Windows companion to hydrogen-api: the /wsl/*, /ab/*, /dock/*, /hbw/*, /widgets/* and legacy /docker/* endpoints, the Windows-only destructive routes, /system reboot, and host-side port discovery. Use when asked about wsl status, ab health, reboot windows, probe-dialogs, or ports.json.

Hydrogen's bridges: the built-in KiCad, Fusion 360 and Puppeteer bridges, the wiki bridge catalog, the Bridge Manager dialog, bridge status, and the Adom Bridge capabilities beneath them. Use when asked about bridges, bridge manager, bridge status, or install a bridge.

Hydrogen's Browser Picker: how every URL opened in Hydrogen is intercepted and routed through the chooser (native profile, Hydrogen tab or window, Pup) with an auto-countdown. Use when a link won't open, for shell.open not allowed, oauth links, or adding a URL-opening feature.

Windows companion to hydrogen-captions: the full-desktop overlay caption (`adom-bridge desktop_caption`, milliseconds) over every app, with ids, positions and force-clear. Use for a desktop caption or a caption over other apps.

Paint caption text on the Hydrogen workspace with `adom-cli hydrogen caption` (seconds, auto-expire, captured by recordings) for demos and walkthroughs. Use when asked to put text on screen, add a caption or callout, label a demo step, or clear a stuck caption.

Windows companion to hydrogen-container-stats: the WSL probe behind the CPU/RAM indicator, `wsl --terminate` as restart, and why the `[docker] unhealthy` log line is benign under WSL. Use for workspace_stats WSL probe or restart needed after wake.

Hydrogen's title-bar workspace stats indicator: the CPU and RAM bars, their tooltip (cores, RAM, disk, image), polling, and the stopped/starting/restart-needed badges. Use when asked about container stats, the resource bars, workspace disk usage, or the restart needed badge.

Windows companion to hydrogen-container: the Adom-Workspace WSL2 distro, its `wsl --import` from the golden image, the distro user and exec model, and code-server 7380 forwarding. Use for Adom-Workspace distro, wsl exec, or distro user questions.

Facts about the Hydrogen workspace Claude runs in: Ubuntu 24.04, code-server, the golden image, setup steps instead of bootstrap.sh, available bridges and the relay. Use when asked what environment am I in, on adom-cli errors, code-server or extension issues, or bridge and relay questions.

Recipe for recording a Hydrogen demo video: human-typed prompt into a Claude tab, the native recorder, getting the mp4 out, then 10-30x speedup and an adom-tts voiceover. Use when asked to record a demo, make a demo video of an app, or show what the app feels like.

Windows companion to hydrogen-desktop-sse: mirrored-networking loopback, ports.json under %APPDATA%, and the legacy Docker-runtime port behavior. Use for WSL2 SSE, ports.json, or same-port loopback questions.

How Hydrogen's local workspace API and SSE stream work, so the workspace's adom-cli controls Hydrogen instead of the cloud: routing, env vars, field formats. Use for Hydrogen SSE, the workspace API, add-tab or move-tab, EventSource, or ADOM_HYDROGEN_URL.

Windows companion to hydrogen-dock: drive the dock from an AI thread through the control API (GET /dock/apps, POST /dock/launch, close, refresh, reset). Use when asked to launch or relaunch a dock app or reset the dock.

Windows companion to hydrogen-eda-discovery: the ready-to-run probe that detects EDA tools with no bridge (Altium, OrCAD, Cadence, EAGLE, DipTrace) via install-path scans and process lists. Use when asked to detect altium or orcad on windows.

Hydrogen's Editor State Machine: how to know the true state of the VS Code editor and its Claude conversations, and the hard rules before typing into one. Use before typing into a Claude tab, or when a prompt landed in the wrong conversation, a split panel is empty, or the state is unknown.

How Hydrogen (ah) runs Adom Bridge (ab) in embedded mode: the hidden tray icon, the Embedded footer pill, why two apps are installed, and how to run ab standalone. Use when asked where is my tray icon, why ab is hidden, why two installs, or to switch ab to standalone.

Move files both ways between the Hydrogen WSL2 workspace and the user's Windows PC: /mnt/c, the \\wsl$ path from Explorer, or adom-bridge send_files/pull_file. Use when asked to copy a file to my desktop, get a file from my PC, move a file in or out, or where my downloads go.

What the pre-baked golden WSL2 image contains, how weekly images and the update-packages step keep it current, and the tarball pin. Maintainer reference for where the CLIs and skills came from.

Hydrogen's lightbulb menu of sample prompts in the title bar: each item opens a fresh Claude thread and types a demo prompt; sample-prompts.json adds or rewords them without a release. Use when asked about the lightbulb, sample prompts, demo prompts, or adding a sample prompt.

Windows companion to hydrogen-naming: the Windows-specific frozen identifiers and install names for Hydrogen and Adom Bridge (appdata folder, installer and exe names, WSL distro, autostart key). Use when asked for a Windows install path or name.

Port architecture, hostnames and networking rules for the Hydrogen workspace: loopback via mirrored networking, the control URL, code-server proxy, relay ports. Read before adding a port or exposing a service to Windows. Use for Hydrogen ports, loopback, proxy, or 7380/8770.

Windows companion to hydrogen-notifications: WinRT toasts through a PowerShell AUMID (an "Adom" title), and the emergency level's persistent orange taskbar flash. Use for windows toast, AUMID, or taskbar flash questions.

How Hydrogen reaches the user outside the window: native OS toasts and attention requests via `adom-bridge notify_user` (levels up to emergency, action buttons), plus the in-app /ui/toast. Use when asked to notify me, send a desktop notification, tell me when it's done, or show a toast.

Decision guide for opening a URL from Hydrogen: webview tab, Hydrogen browser window, Pup, a native browser profile, the Browser Picker, or a headless fetch, and when to use each. Use when asked to open a website, open a link, pull up a page, open in a tab, or which browser to use.

Windows companion to hydrogen-permissions: the WebView2 PermissionRequested handler that allows every permission kind. Use for webview2 permission or PermissionRequested questions.

Hydrogen auto-grants every webview permission (mic, camera, clipboard, geolocation, notifications), so a webview app never shows an Allow prompt; the AI's screen-share consent is separate. Use when building a webview app with getUserMedia or clipboard, or asked why there is no permission prompt.

Why you don't need port forwarding in Hydrogen: under WSL2 mirrored networking every port the workspace binds, including 127.0.0.1 OAuth callbacks, is reachable on Windows localhost. Use when asked about port forwarding, OAuth callback ports, Codex or extension auth, or why can't I reach my port.

How ports reach Windows from the Hydrogen WSL2 workspace: WSL2 localhost forwarding, the code-server /proxy/<port>/ URL, the port-forward registry for 127.0.0.1-only services, and the Port Mappings dialog. Use when asked why my server isn't reachable, how to expose a port, or what localhost:7380 is.

Hydrogen's Project workspaces menu (icon right of the Adom logo) and its API: apply or unload the bench layout a project ships in hydrogen/workspace.json. Use when asked about project workspaces, apply a bench, workspace.json, or the workspace offer card.

Record the screen, a window or audio from Hydrogen with the native recorder (`adom-cli hydrogen recording`): H.264/H.265 mp4, wgc or gdigrab engines, multi-monitor, duration cap. Use when asked to record my screen, record kicad, record narration, or why a recording has 0 frames.

Which runtime hosts your Hydrogen workspace: the WSL2 Adom-Workspace distro (default) or a legacy Docker container (HD_RUNTIME=docker), how to tell, and what differs. Use when asked am I in docker or wsl, which runtime, or when workspace networking, ports or setup advice conflicts.

Hydrogen screen capture and the display wake-lock: why native screenshots and recordings don't block the screensaver, and the start, capture, release and cap rules. Use when the display won't sleep, the screensaver is blocked, or before adding a screenshot or recording feature.

Screenshot Hydrogen from inside the workspace: a panel, the whole workspace, or the whole screen with `adom-cli hydrogen screenshot`, or one element with POST /screenshot and a CSS selector. Use when asked to screenshot the welcome page, a webview, a menu, my whole screen, or to verify a UI change.

Windows companion to hydrogen-setup-steps: the WSL2 step cascade, the `wsl --import Adom-Workspace` step, `wsl --unregister` virgin-reset mechanics, setup-steps-wsl.json and the golden tarball. Use for the exact WSL2 steps or file paths.

What Hydrogen's setup steps did to prepare the workspace: provision the golden image, inject the Adom session, wire the relay, walk the Claude auth gate. Use when asked what did setup do, why is X installed, re-run a setup step, why did step N fail, or what a virgin reset is.

Windows companion to hydrogen-setup: the WSL2 install cascade, the ensure-workspace import, `wsl --unregister Adom-Workspace` virgin reset, setup-steps-wsl.json, and the never-touch-global-WSL rule. Use for exact WSL2 setup commands or file paths.

Hydrogen's setup panel: the install-step cascade, Run All, Rollback All, Virgin Reset with its toggles, keeping auth during resets, and test patterns. Read before running setup or a virgin reset. Use when asked about the setup panel, run all, a failed step, or reset workspace.

Maintainer loop (Windows/ah) for fixing a wrong Hydrogen skill: verify against the running Hydrogen, fix the live copy, fix the text source (ah repo for hydrogen-* bootstrap skills, else the wiki page repo), publish. Companion to hydrogen-skill-loop. Use when a skill is wrong or stale.

Where Claude runs relative to Hydrogen: inside the local Adom-Workspace WSL2 distro, or in a cloud container driving the user's PC through the relay, and how to reach Windows and the workspace from each. Use when asked where am I, cloud vs local, wsl exec, reach the workspace, or adom-bridge relay.

Hydrogen's interface (menus, dialogs, panels, profile menu, setup panel) and how to drive it from the workspace via the UI command bus (GET /ui/actions, POST /ui/invoke) instead of clicking. Use when asked to open or close a Hydrogen dialog or menu, or where a UI element is.

Where files live in Hydrogen's WSL2 workspace, what survives a restart versus a virgin reset, and how to reach them from Windows. Use when asked where are my files, did I lose my work, how do I copy a file out, or what happens to my code if I virgin reset.

How Hydrogen repairs the workspace connection after the laptop wakes from sleep: the wake-heal cascade, the header wake indicator, Settings > Desktop > Wake, and the /wake/* API. Use when Hydrogen didn't reconnect after sleep, a cannot reconnect dialog appears, or asked about the sunrise icon.

Windows companion to hydrogen-webview: hbw, Hydrogen's standalone built-in browser window (POST /hbw/open). Use when asked for a hydrogen browser window or a standalone browser window.

Build, list, open and drive Hydrogen Widgets, small live panels in the Title Bar (Claude usage, Codex usage, your own): the hydrogen-widget.json facet, launch contract, and /widgets API. Use when asked to make a widget, add a title bar widget, or about the usage meter widget.

Lifecycle of Hydrogen's Adom-Workspace WSL2 distro: import, export, unregister, terminate, code-server as Hydrogen's child, recovery after sleep, and the rule to never run global WSL commands. Read before any workspace operation. Use when the workspace is broken, unhealthy, or needs a restart.

Windows companion to hydrogen-workspace-monitoring: the WSL2 Not Available floaty, `wsl --terminate Adom-Workspace`, the code-server 7380 check, and why WSL has no daemon. Use for WSL2 workspace states, commands or ports.

How Hydrogen monitors the local workspace and code-server: the 15 s state poll, health levels, the status floaty, auto-start, iframe auto-reload, and the lifecycle dialog. Use when asked why the workspace stopped, about the workspace floaty, or before changing workspace state code.

WSLg (Linux GUI apps from the Hydrogen workspace) is off by default: check it, turn it on or off through Hydrogen's control API, apply with a workspace restart, and handle the RemoteApp security warning. Use when asked about wslg, a linux gui app, cannot open display, or enable gui apps.