main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-doctor description: >- The Hydrogen Doctor on Linux: a one-click health scan of the whole stack (workspace machine, code-server, Claude, Adom auth, ports, relay, Adom Bridge), also at GET/POST /doctor. Use when something is broken and nobody knows what, things are weird after the computer sleeps, or to run the doctor.

Hydrogen Doctor: diagnose the whole stack in one place

The Doctor answers "is everything actually working?" with evidence: about 20 real checks end to end (not "is the process alive" but "does it answer correctly"), each with a plain-English explanation.

Where it lives

  • UI: Adom menu (top-left) → Doctor.... A dialog lists every check with a green/red state; hovering a row reveals a paragraph explaining what that check means and why it matters. Buttons: Re-run checks, Fix problems, and (only when recommended) Restart workspace.
  • API (Hydrogen control API, see hydrogen-api for the port):
    • GET /doctor runs all checks: {before: {checks: [...]}, still_failing, ...}, each check with ok and message.
    • POST /doctor body {"fix": true} runs checks, tries the safe fix (none exists on Linux yet, see below), and returns {before, after, actions, still_failing, recommend_workspace_restart}.

What it checks

Workspace side: the workspace helper responds (the helper hydrogen-workspace and machinectl answer), the runtime is the Adom-Workspace systemd-nspawn machine (workspace), the Adom API key exists (api-key), required env vars are exported (env-vars), adom-cli is installed (adom-cli) and can actually reach Adom's cloud (adom-cli-api), skills are deployed (skills), the in-container relay answers on 8765/8766 (relay).

Editor side: code-server is genuinely serving (code-server, the big one after sleep), the required extensions are installed (extensions), Claude Code CLI is installed (claude-installed) and signed in (claude-auth), the live SSE link between editor and app is up (sse), the workspace-layout API responds (webview).

Plumbing: workspace service ports reachable from this computer (ports), identity (identity), the relay path for Adom Bridge (adom-bridge), ab's direct API (adom-bridge-direct), and port-integrity (code-server serving; a control API that moved off 47084 is a note, not a failure).

adom-bridge-direct is red whenever no Adom Bridge runs on this computer. Hydrogen installs and starts it when a Linux build is published for the user's account, so red is expected only when none is published yet (the setup step says so). If one is installed (~/.local/share/adom-bridge-app/run.sh) and it stays red, read the [ab-linux] and [ad-supervisor] log lines.

Repair on Linux

  • Fix problems has no automatic heal on Linux: the heal cascade it triggers exists only on the other platforms, so actions says "Heal cascade unavailable" and the checks are not re-run. Read the failures and fix them directly.
  • Restart workspace (disruptive, confirm-gated): POST /container-restart stops the machine and starts it again, reloading VS Code and Claude ({"dry_run":true} says what it would do). Never trigger it without the user's OK.
  • A red "Workspace helper responds" means the helper or machinectl did not answer: restart the workspace from the Adom menu, then restart Hydrogen if that does not help.

How you (the AI) should use it

  • User says "nothing works" or "it froze after I opened my laptop": call GET /doctor first and READ the failures instead of guessing.
  • Fix what the failures name (restart a service, sign in, start code-server).
  • Offer a workspace restart only when the failures point at the machine itself, and ask first.
  • After any repair, re-run GET /doctor and only claim health you can see (all ok: true).
  • hydrogen-wake-repair: what happens after sleep on Linux (the Cannot reconnect watcher).
  • hydrogen-workspace-lifecycle: what a workspace restart actually does.
  • hydrogen-api: how to find the control port.