Adom Hydrogen

@@ -1,41 +1,41 @@ # Claude Conversation Management — and taking a conversation to claude.ai / your phone -Hydrogen Desktop runs Claude Code as **conversation tabs** inside the editor. HD exposes a+Hydrogen runs Claude Code as **conversation tabs** inside the editor. Hydrogen exposes a **first-class API** to manage those conversations — list them, open and close them, switch between them, read each one's full state, type into a specific one, and **turn on Remote Control so you can continue the same conversation on claude.ai or the Claude mobile app**. -Everything here works for **you**, for the **AI inside your workspace**, and for HD's own+Everything here works for **you**, for the **AI inside your workspace**, and for Hydrogen's own setup steps — they all call the same endpoints. It all runs in the background: no window focus, no stolen keystrokes. -![Multiple Claude conversations as tabs in Hydrogen Desktop](screenshots/claude-conversations.png)+![Multiple Claude conversations as tabs in Hydrogen](screenshots/claude-conversations.png)  ## Why this matters  - **Run several conversations at once** and drive each independently — one mapping your   design stack, one wiring up pricing, one answering a quick question — all   scriptable.-- **Keep going on your phone.** Turn on Remote Control and HD hands you a `claude.ai` URL.+- **Keep going on your phone.** Turn on Remote Control and Hydrogen hands you a `claude.ai` URL.   Open it in any browser or the Claude mobile app and you're looking at — and controlling —-  the *same* conversation in the cloud. Start at your desk in HD, continue from the couch on+  the *same* conversation in the cloud. Start at your desk in Hydrogen, continue from the couch on   your phone.-- **Nothing gets lost.** Every conversation is stored as a local log you can read, and HD+- **Nothing gets lost.** Every conversation is stored as a local log you can read, and Hydrogen   can hand you its session id automatically.  ## The model: every conversation has a stable id  Each conversation is addressed by a stable **`context_id`**. That's how you reliably target one — not its tab position (tabs come and go) and not its title (untitled until you send a-message). Ask HD for the list, then act on a conversation by its id.+message). Ask Hydrogen for the list, then act on a conversation by its id. -> The control API runs on a dynamic local port — find it in the HD log or via port-> discovery. Examples below use `$HD` for `http://127.0.0.1:<port>`.+> The control API runs on a dynamic local port — find it in the Hydrogen log or via port+> discovery. Examples below use `$Hydrogen` for `http://127.0.0.1:<port>`.  ## See what's open  ```bash-curl -s $HD/claude/conversations+curl -s $Hydrogen/claude/conversations ``` ```jsonc {@@ -65,23 +65,23 @@ curl -s $HD/claude/conversations ## Open, close, switch  ```bash-curl -s -X POST $HD/claude/new-conversation       # open a new conversation tab-curl -s -X POST $HD/claude/tabs/close-all          # close them all (and clean the blank panel)-curl -s -X POST $HD/claude/tabs/activate -d '{"label":"Eiffel"}'   # switch by title-curl -s -X POST $HD/claude/tabs/close-empty-groups # remove a stale empty split panel+curl -s -X POST $Hydrogen/claude/new-conversation       # open a new conversation tab+curl -s -X POST $Hydrogen/claude/tabs/close-all          # close them all (and clean the blank panel)+curl -s -X POST $Hydrogen/claude/tabs/activate -d '{"label":"Eiffel"}'   # switch by title+curl -s -X POST $Hydrogen/claude/tabs/close-empty-groups # remove a stale empty split panel ```-HD keeps your editor tidy: it removes leftover **empty** editor panels automatically on+Hydrogen keeps your editor tidy: it removes leftover **empty** editor panels automatically on launch, while **preserving** an intentional two-group (left/right) layout if you use one.  ## Type a message into a specific conversation  ```bash # Instant (fast):-curl -s -X POST $HD/claude/inject \+curl -s -X POST $Hydrogen/claude/inject \   -d '{"text":"summarize this repo","context_index":16,"typed":false,"submit":true}'  # With the human typing animation, then send:-curl -s -X POST $HD/claude/inject \+curl -s -X POST $Hydrogen/claude/inject \   -d '{"text":"hello","context_index":16,"typed":true,"delay_ms":50,"submit":true}' ``` - `typed`: `true` = animated character-by-character; `false` = instant paste.@@ -92,7 +92,7 @@ curl -s -X POST $HD/claude/inject \ ## ⭐ Remote Control: continue on claude.ai / your phone  ```bash-curl -s -X POST $HD/claude/remote-control -d '{"context_index":7}'+curl -s -X POST $Hydrogen/claude/remote-control -d '{"context_index":7}' ``` ```jsonc {@@ -112,11 +112,11 @@ on an already-on conversation just returns the existing URL (it won't switch it `{enable:false}` turns it off. Each conversation's state shows up as `rc_active` in `/claude/conversations`. -## How HD knows which on-disk log is which conversation+## How Hydrogen knows which on-disk log is which conversation  Claude stores each conversation as `~/.claude/projects/<project>/<uuid>.jsonl` (with its `sessionId`, generated title, and every message). The conversation's webview doesn't expose-that GUID, so HD matches a live conversation to its log by the **first user message** — exact+that GUID, so Hydrogen matches a live conversation to its log by the **first user message** — exact and unique — then fills in the `session_id` and the authoritative title for you. So you never have to hunt through log files by hand; `GET /claude/conversations` gives you the id directly. @@ -127,7 +127,7 @@ cat ~/.claude/projects/*/<session_id>.jsonl  ## For the AI in your workspace -Your in-workspace AI can do all of the above. The bundled **`hd-claude-management`** skill+Your in-workspace AI can do all of the above. The bundled **`hydrogen-claude-management`** skill documents every endpoint with examples, so you can ask things like *"open three conversations and ask each a different question"* or *"turn on remote control for this conversation and give me the link for my phone."*

@@ -0,0 +1,129 @@+# Driving Hydrogen remotely (via Adom Desktop verbs)++You are (often) an AI in an **Adom cloud container**. The user's **Hydrogen (ah)** runs+on **their Windows laptop**, with a **WSL2 workspace** inside it. You reach all of it through the+**`adom-desktop` CLI** — the Adom Desktop (ab) relay. Don't SSH, don't hand-roll transports; use+the verbs.++```+  cloud container (you)  ──adom-desktop──▶  ab on the laptop  ──▶  Hydrogen app  ──▶  WSL2 workspace+        Tier 1                               Tier 2                 │            (code-server,+                                                                    └─ control API   claude, tools)+                                                                       (dynamic port)+```++Discover everything: `adom-desktop help`, `adom-desktop help <namespace>`,+`adom-desktop help <verb>`, `adom-desktop commands` (full JSON catalog).++## Call Hydrogen's control API with `hd_api` — NOT curl++Hydrogen exposes a large control API on a **dynamic localhost port**. To call ANY endpoint:++```bash+adom-desktop hd_api '{"path":"/claude/conversations"}'+adom-desktop hd_api '{"path":"/claude/inject","method":"POST","body":{"text":"hi","context_index":7,"submit":true}}'+```+Returns `{ok, status, body, port, ...}` with `body` already parsed as JSON.++- **`hd_api` auto-discovers the port** (from `ports.json`, falls back to 47084) and takes a real+  JSON `body` — no escaping.+- ❌ **MISTAKE TO AVOID:** calling the control API via `shell_execute "curl …"`. The relay mangles+  nested quotes, you hardcode a port that changes between launches, and you burn time on escaping.+  `hd_api` exists precisely so you never do this.++## The Hydrogen lifecycle / dev verbs (`hd` namespace)++| Verb | Use |+|---|---|+| `hd_status` | Composed snapshot of Hydrogen state |+| `hd_log` | Tail Hydrogen's log (`%APPDATA%/hydrogen-desktop/hydrogen-desktop.log`) |+| `hd_shot` `{region}` | Screenshot an Hydrogen region (full/vscode/wiki/claude…) → returns local PNG path |+| `hd_launch` / `hd_stop` / `hd_restart` | Start (detached) / kill / both |+| `hd_build_rust` `{show}` + `hd_build_status` | Rust build (async) + poll until `building:false`, assert `succeeded` |+| `hd_build_frontend` | Frontend-only build |+| `hd_ship` | Atomic rebuild-from-pushed-SHA + relaunch + verify |+| `hd_send_files` | Push files straight into the WSL2 project |+| `hd_open_url` | Open a URL in a specific browser profile via Hydrogen |++- ⚠️ **Control port intermittently fails to bind on a launch.** If `hd_api` says "Hydrogen not+  reachable", check `netstat` for the control port on Hydrogen's PID; a `hd_restart` usually fixes it.+- ⚠️ Don't trust a build's SHA stamp to confirm "my code shipped" — verify by behavior (call the+  new endpoint) or a code-marker, not the stamp.++## Run things on the laptop + in the workspace++```bash+# Windows (cmd, NOT PowerShell) on the laptop:+adom-desktop shell_execute '{"command":"tasklist | findstr hydrogen","timeoutSeconds":15}'+# Read .stdout / .stderr from the result — NOT .output (parsing .output comes back empty).++# Multi-line / quote-heavy scripts — base64 them, no quoting survives mangling otherwise:+adom-desktop run_script '{"interpreter":"powershell","scriptB64":"<b64>"}'++# Inside the WSL2 workspace (the Linux side: claude logs, ~/.claude, project files):+adom-desktop wsl_exec '{"distro":"Adom-Workspace","user":"adom","scriptB64":"<b64>"}'+```+- `shell_execute` runs in **cmd.exe** — `Start-Process` etc. need `powershell -NoProfile -Command "…"`.+- Long jobs (builds) must be launched **detached** and polled; the relay has a ~30–120s timeout.++## Move files++```bash+adom-desktop send_files '{"filePaths":["/tmp/x.json"],"dest":"C:/Users/<you>/Downloads"}'+adom-desktop pull_file  '{"filePaths":["C:/path/to/file.png"],"saveTo":"/tmp"}'+```+- ⚠️ `dest` is a **folder** (the file keeps its basename). Files whose basename starts with `_`+  are silently dropped — use plain names.++## Drive the real OS / windows (`desktop` namespace, 80+ verbs)++Two modes — **always prefer background**:++- **BACKGROUND (no focus steal):** `desktop_screenshot_window {hwnd}`, `desktop_find_window+  {titleContains}`, `desktop_find_control {hwnd,name|contains|role}` (reports rect + invokable ++  settable), `desktop_ui_click` (UIA Invoke), `desktop_ui_set` (UIA SetValue), `desktop_ui_focus`,+  `desktop_navigate` (set a browser omnibox without foreground).+- **FOREGROUND (SendInput — steals focus, risky):** `desktop_bring_to_front {hwnd}`,+  `desktop_click {x,y}`, `desktop_type {text}`, `desktop_press_key {keys}`.++### ❌ The biggest mistake: blind synthetic typing++`desktop_type` / `desktop_press_key` send OS-level keystrokes to whatever window currently has+focus. If your target window isn't reliably foregrounded, **your keystrokes land in the WRONG+window** — including the user's own chat with you. (This actually happened: a test marker typed+"into a web page" instead got submitted into the operator's chat.) Rules:++1. Prefer **background** verbs: `desktop_ui_set` / `desktop_ui_click` by accessible name — no+   focus, no cursor move. Chromium/Edge expose their a11y tree, so most page buttons/inputs are+   reachable this way.+2. If a field is **shadow-DOM** (`desktop_find_control` returns `settable:false, invokable:false`+   — common for modern web apps like the claude.ai composer), UIA can't set it. Use the+   **native-browser CDP bridge** (`nbrowser_*`, install via `bridge_install`) to type into the+   page over CDP. Do NOT fall back to blind SendInput.+3. If you MUST use SendInput: `desktop_bring_to_front {hwnd}`, then **verify** the target is+   actually foreground before typing, and confirm the result landed where you intended.+4. `desktop_find_control` gives `rect.centerX/centerY` (screen px) for a precise `desktop_click`+   — but the window must be on top at that point or you click whatever is there.++## Worked example: open a Claude conversation on claude.ai from the cloud++```bash+# 1. find a conversation + its cloud URL (Remote Control)+adom-desktop hd_api '{"path":"/claude/conversations"}'+adom-desktop hd_api '{"path":"/claude/remote-control","method":"POST","body":{"context_index":7}}'+#    → body.remote_control_url = https://claude.ai/code/session_…+# 2. open it in the user's Chrome (new window)+adom-desktop shell_execute '{"command":"powershell -NoProfile -Command \"Start-Process chrome.exe -ArgumentList '"'"'--new-window'"'"','"'"'<url>'"'"'\""}'+# 3. screenshot to confirm — background, no focus steal+adom-desktop desktop_find_window '{"titleContains":"Claude Code - Google Chrome"}'   # → best.hwnd+adom-desktop desktop_screenshot_window '{"hwnd":<hwnd>}'                              # → local PNG path+```++## Checklist before you act++- Reaching Hydrogen's API? → `hd_api`, not curl.+- Reading a command's output? → `.stdout`/`.stderr`, not `.output`.+- Typing into a window? → background UIA / CDP first; only SendInput after foreground+verify.+- Long build? → launch detached, poll `hd_build_status`, verify by behavior.+- Port "not reachable"? → it's dynamic and sometimes doesn't bind; `hd_restart`.+- Moving files? → `dest` is a folder; no leading-underscore basenames.

@@ -1,49 +1,49 @@-# Installing Hydrogen Desktop — the full walkthrough+# Installing Hydrogen — the full walkthrough  This is the complete first-run experience, screen by screen — from downloading the installer to a fully configured AI electronics-design workspace. The whole thing takes **~2–4 minutes** on a-typical machine (most of it the one-time workspace download), and it's **hands-off**: HD drives the+typical machine (most of it the one-time workspace download), and it's **hands-off**: Hydrogen drives the setup and you just watch it tick green. There are only **two human moments** — signing in to Adom and signing in to Claude. -> New here? Start on the [Hydrogen Desktop page](https://wiki.adom.inc/adom/hydrogen-desktop) and+> New here? Start on the [Hydrogen page](https://wiki.adom.inc/adom/hydrogen-desktop) and > grab the latest signed `Hydrogen.Desktop_…_x64-setup.exe` from the **Releases** tab.  ---  ## 1 · Download & run the installer -Download the signed `Hydrogen Desktop … x64-setup.exe` from the Releases on the page and run it.+Download the signed `Hydrogen … x64-setup.exe` from the Releases on the page and run it. It's signed by **Adom Industries, Inc.** (the same publisher as Adom Desktop), so Windows-SmartScreen recognizes it. It installs **per-user — no admin prompt** — and launches HD when it+SmartScreen recognizes it. It installs **per-user — no admin prompt** — and launches Hydrogen when it finishes. -![The Hydrogen Desktop installer](screenshots/install.png)+![The Hydrogen installer](screenshots/install.png)  ---  ## 2 · Sign in to Adom  *(human moment #1)* -The one thing HD needs from you up front is your Adom account — that's your identity and your-toolchain. HD opens the sign-in page and brings it to the front; you click **Approve**, and HD+The one thing Hydrogen needs from you up front is your Adom account — that's your identity and your+toolchain. Hydrogen opens the sign-in page and brings it to the front; you click **Approve**, and Hydrogen takes over from there. (Your Adom account is identity only — the work runs locally on your machine.) -![Authorize Hydrogen Desktop with your Adom account](screenshots/adom-signin.png)+![Authorize Hydrogen with your Adom account](screenshots/adom-signin.png)  --- -## 3 · HD builds your Linux workspace (WSL2)+## 3 · Hydrogen builds your Linux workspace (WSL2) -HD's first and biggest job is creating the Linux environment everything else runs in: a dedicated+Hydrogen's first and biggest job is creating the Linux environment everything else runs in: a dedicated **WSL2 Ubuntu 24.04** distro called **`Adom-Workspace`**, provisioned from a pre-baked, SHA-verified ~400 MB "golden" image. -If your PC doesn't have WSL2 yet, HD turns it on for you — **the one point where Windows needs a-single reboot.** After the restart, HD picks right back up on its own. You may briefly see Windows'-own **"Welcome to Windows Subsystem for Linux"** window pop up during this step; HD works around it+If your PC doesn't have WSL2 yet, Hydrogen turns it on for you — **the one point where Windows needs a+single reboot.** After the restart, Hydrogen picks right back up on its own. You may briefly see Windows'+own **"Welcome to Windows Subsystem for Linux"** window pop up during this step; Hydrogen works around it and keeps going — you don't need to touch it. -HD then imports the image, starts **code-server** (VS Code in the browser) inside the distro, and+Hydrogen then imports the image, starts **code-server** (VS Code in the browser) inside the distro, and **refuses to advance until the environment is genuinely up and answering.**  ![Workspace runtime ready](screenshots/01_ensure-workspace_done.png)@@ -52,7 +52,7 @@ HD then imports the image, starts **code-server** (VS Code in the browser) insid  ## 4 · The automated setup cascade (20 steps, streamed live) -With the workspace up, HD runs the rest of setup automatically, streaming every step live in the+With the workspace up, Hydrogen runs the rest of setup automatically, streaming every step live in the Setup panel. Each step proves it actually worked before the next begins.  **Wire up the editor & platform**@@ -74,7 +74,7 @@ Setup panel. Each step proves it actually worked before the next begins. | `ensure-adom-desktop` | Confirms the **Adom Desktop** companion (the bridge to your real machine) is running. | | `start-relay` | Starts the in-workspace relay that connects to Adom Desktop. | | `test-direct-connect` / `test-relay` | Tests both the fast direct path and the file-transfer path. |-| `test-adom-cli` | **Hard gate:** `adom-cli` must reach Adom on *both* the cloud and proxy routes — if not, HD stops here rather than limp forward. |+| `test-adom-cli` | **Hard gate:** `adom-cli` must reach Adom on *both* the cloud and proxy routes — if not, Hydrogen stops here rather than limp forward. |  ![Connectivity verified](screenshots/11_test-adom-cli_done.png) @@ -82,9 +82,9 @@ Setup panel. Each step proves it actually worked before the next begins.  ## 5 · Sign in to Claude  *(human moment #2)* -HD installs the Claude Code CLI (`install-claude-cli`), then reaches the **one step that needs-you again**: signing in to Claude. HD restores your saved Claude credentials if they're still-valid; otherwise it opens the Claude consent in the browser and you click **Authorize**. HD+Hydrogen installs the Claude Code CLI (`install-claude-cli`), then reaches the **one step that needs+you again**: signing in to Claude. Hydrogen restores your saved Claude credentials if they're still+valid; otherwise it opens the Claude consent in the browser and you click **Authorize**. Hydrogen deliberately saves this single human moment for last, after all the hands-off work is done.  ![Sign in to Claude — the Authorize screen](screenshots/claude-signin.png)@@ -95,7 +95,7 @@ deliberately saves this single human moment for last, after all the hands-off wo  ## 6 · Final verification + your first AI conversations -HD finishes by proving the whole thing is healthy and opening your first AI threads for you:+Hydrogen finishes by proving the whole thing is healthy and opening your first AI threads for you:  | Step | What it does | |---|---|@@ -117,11 +117,11 @@ When the cascade finishes you're looking at a fully configured editor with **Cla your Welcome page open, and a live **bridge to your real desktop** so the AI can drive KiCad and Fusion 360. From one installer to a working local AI workspace, hands-off, in a few minutes. -![Hydrogen Desktop, fully set up](screenshots/workspace.png)+![Hydrogen, fully set up](screenshots/workspace.png)  ---  *Trouble? See the **Troubleshooting** section on the [main page](https://wiki.adom.inc/adom/hydrogen-desktop). The most common one: if you step away during the Claude sign-in and the link times out, just click **"Sign in again"** then **Authorize**-— HD picks it up and finishes.*+— Hydrogen picks it up and finishes.*