Hydrogen Desktop (macOS / Lima)

The macOS platform layer (adompkg bootstrap) for Hydrogen Desktop — converges a Lima/nspawn Linux workspace to "ready to run inside HD on a Mac". Depends on adom/hd-bootstrap; bundles the macOS-runtime hd-* skills. Installed by the golden Lima image (hd-lima-image). Not an interactive skill — this is a bootstrap package.

Diagnose and repair the workspace's Adom API key (`/var/run/adom/api-key`) on macOS Hydrogen Desktop — the injected session token that adom-cli and every Adom tool authenticate with. Use when adom-cli returns 401/unauthorized, `/var/run/adom/api-key` is missing or empty, "adom-cli can't reach Adom", or the user asks to reauthorize Adom / re-pull the API key. Covers: pulling the current token from HD via `GET /auth-token`, re-writing the key (passwordless sudo), prompting the user to sign in to HD when the host has no valid session, and triggering HD's inject-api-key setup step. Trigger words — api key, api-key, /var/run/adom, 401 unauthorized, adom-cli auth, reauthorize adom, re-auth adom, pull api key, session token missing, fix adom auth, carbon 401.

macOS platform companion to hd-api — the Apple/Lima-specific half of reaching HD's control API. The full endpoint catalog lives in hd-api (adom/hd-bootstrap); THIS skill carries only what differs on macOS: the adom-host gateway (vz doesn't mirror loopback), the ~/.adom/hd-control-url discovery file, HD binding 0.0.0.0, and the nspawn machine-runtime endpoints (the /workspace/* routes, /wsl/* names kept for wire-compat). Mirror of hd-api-windows (the /wsl/* WSL networking tables). Trigger words — hd control api macos, adom-host, hd-control-url, reach HD from the workspace, machine runtime endpoints, vz loopback, workspace health macos.

macOS platform companion to hd-browser-picker — the Apple-specific half of how Hydrogen Desktop intercepts EVERY URL and routes it through the Browser Picker. The picker dialog, the 3 branded variants, the 5-second auto-countdown, the fresh-window toggle, and the prefs API all live in hd-browser-picker (adom/hd-bootstrap); THIS skill carries only what's wired differently on macOS: the top frame is a WKWebView served over http://localhost (not WebView2), and the native-browser targets are launched via LaunchServices (`open -a`). Mirror of hd-browser-picker-windows (the WebView2 / ICoreWebView2 COM / 6-layer machinery). Trigger words — browser picker macos, WKWebView interception, open -a, native browser macos, Safari Chrome Arc Edge, localhost top frame, shell.open macos.

macOS platform companion to hd-captions — the Apple-specific note on HD's on-screen captions. The two caption surfaces, the SECONDS-vs-MILLISECONDS unit trap, ids, positions, and the adom-cli / HTTP commands all live in hd-captions (adom/hd-bootstrap) and are platform-neutral; THIS skill carries only the one macOS difference: the full-DESKTOP overlay (adom-desktop desktop_caption) is a Win32 click-through window and is NOT implemented on macOS yet (the non-Windows build is a stub). The workspace caption (adom-cli hydrogen caption) works the same on macOS. Mirror of hd-captions-windows. Trigger words — caption macos, desktop_caption macos, desktop overlay mac, screen overlay mac, caption not showing mac, click-through caption mac.

HD's workspace stats indicator in the top-right of the title bar — two thin progress bars (CPU + RAM) labelled "Container" plus an info tooltip on hover that shows the workspace name, CPU vs total cores, RAM usage vs limit, disk usage, image/machine, ID, and creation date. Polls once per second when running, every 5 seconds when stopped. Status badges show stopped / starting / restarting / restart-needed states. Use this skill when the user asks about CPU/RAM usage, the resource bars in HD's title bar, workspace disk usage, the "restart needed" badge, why bars are red/yellow, or what's in the tooltip. Trigger words — container stats, workspace stats, container cpu, container ram, container disk, resource bars, cpu bar, ram bar, container tooltip, container indicator, top bar stats, restart needed badge, container stopped badge, container starting, workspace_stats, machine stats, machine runtime stats.

Context for Claude Code running inside a Hydrogen Desktop workspace machine. Documents the exact OS (Ubuntu 24.04, code-server 4.112.0, the Adom-Workspace machine), explains how setup differs from Adom cloud containers (setup-steps NOT bootstrap.sh), what bridges are available, and how to use the relay. Trigger on startup, adom-cli errors, bridge commands, screenshot requests, container-platform questions, code-server / VS Code extension issues, or when the AI needs concrete facts about its environment instead of guessing.

Port architecture, hostnames, and networking rules for Hydrogen Desktop. MUST READ before adding ports, exposing a service to your macOS host, referencing host URLs from inside the workspace, or wiring any service communication. Trigger words — HD port, HD network, port mapping, proxy, 127.0.0.1, loopback, adom-host gateway, hd-control-url, VSCODE_PROXY_URI, relay URL, code-server proxy, container networking, ADOM_CARBON_URL, ADOM_HYDROGEN_URL, direct connect, 8770, 7380.

macOS platform companion to hd-notifications — the Apple-specific half of how Hydrogen Desktop reaches the user outside the window. The generic notify handler, payload shape, levels, and /ui/toast live in hd-notifications (adom/hd-bootstrap); THIS skill carries only the macOS delivery mechanics: Notification Center toasts, the emergency Dock-icon attention bounce, and the System Settings → Notifications grant. Mirror of hd-notifications-windows (WinRT/AUMID). Trigger words — macos notification, notification center, dock bounce, request attention macos, allow notifications macos, toast on mac.

macOS platform companion to hd-open-url — the Apple-specific half of "open a URL in a native browser". The six ways to open a URL (Hydrogen webview tab, HD window, Pup, native browser, the Browser Picker, headless curl), the decide-for-the-user rule, the /open-url + /open-in-profile + prefs API all live in hd-open-url (adom/hd-bootstrap); THIS skill carries only the macOS native-browser mechanics: launching via LaunchServices (`open` / `open -a "<App Name>"` / `--new-window` fresh windows), macOS browser-profile dirs, and the control-URL discovery file (~/.adom/hd-control-url). Mirror of hd-open-url-windows (chrome.exe/msedge.exe by path). Trigger words — open url macos, open -a, native browser mac, Safari Chrome Arc Edge, fresh window mac, browser profiles mac, hd-control-url.

macOS platform companion to hd-permissions — the Apple-specific half of the permission story. The generic skill (adom/hd-bootstrap) covers HD's webview auto-grant: inside HD a webview app NEVER sees a "site wants to use your microphone/camera/clipboard/location" prompt. THIS skill carries only what's macOS-specific: the OS-level TCC privacy model (Screen Recording, Accessibility, Automation, Camera, Microphone) granted under System Settings → Privacy & Security, how HD preflights/requests them (CGPreflightScreenCaptureAccess, AXIsProcessTrustedWithOptions), and that some need a relaunch / a stable signing identity to stick. Mirror of hd-permissions-windows (UAC, no per-feature gate). Trigger words — macos permissions, TCC, screen recording permission, accessibility permission, automation permission, privacy and security, AXIsProcessTrusted, CGPreflightScreenCaptureAccess, grant accessibility, relaunch to take effect.

Dynamic port forwarding for Hydrogen Desktop. A daemon inside the Adom-Workspace machine watches for new TCP listeners (OAuth callbacks from VS Code extensions like Codex, Copilot, GitLens) and notifies HD to create host-side TCP proxies. Covers the cases macOS/Lima port exposure can't: `127.0.0.1`-only listeners and exposure gaps. Makes localhost:{port} on the Mac reach the machine. Extensions just work — no manual setup. Trigger words: port forward, dynamic port, OAuth callback, Codex auth, extension auth, port mapping, localhost port, port watcher, port proxy.

How HD does port forwarding between your workspace machine and your Mac — Lima's `0.0.0.0` port exposure (no Docker `-p` map), the code-server `/proxy/<port>/` URL pattern that exposes any internal port, the port-forward registry for `127.0.0.1`-only services that macOS won't expose, and the PortMappingsDialog UI. Use when the user asks "why isn't my server reachable", "how do I expose port X", "what's localhost:7380", "register a port", "expose a port", or "the dynamic port dialog". Trigger words — port forwarding, ports, hd ports, container port, proxy port, code-server proxy, /proxy/, port mappings dialog, port hints, expose port, register port, host port, dynamic port, ports.json, PortConfig, port resolver, localhost port not working.

macOS platform companion to hd-recording — the Apple-specific half of recording screen + window video from Hydrogen Desktop. The recorder ladder, codec choice, the max-duration cap, audio-only narration, and the "● Recording" indicator live in hd-recording (adom/hd-bootstrap); THIS skill carries only what's true on macOS: HD's native recorder is NOT available here (it's #![cfg(windows)]), so recording goes through the in-app getDisplayMedia recorder, pup per-tab, or the AD desktop relay — and the Screen Recording TCC grant gates the desktop paths. Mirror of hd-recording-windows (the native WGC/DXGI recorder). Trigger words — record macos, screen recording mac, record kicad mac, native recording windows-only, screencapturekit, avfoundation, getdisplaymedia mac, screen recording permission, tcc grant recording, desktop_record_start macos.

macOS platform companion to hd-screen-lock — the Apple-specific half of the display wake-lock that a getDisplayMedia capture asserts. The cross-platform story (HD is native → CDP screenshots hold no lock; the recording cap + "● Recording" indicator; the contention guard) lives in hd-screen-lock (adom/hd-bootstrap); THIS skill carries only the macOS power-assertion mechanics: the IOKit IOPMAssertion (PreventUserIdleDisplaySleep), diagnosing the holder with `pmset -g assertions`, and `caffeinate`. Mirror of hd-screen-lock-windows (SetThreadExecutionState / ES_DISPLAY_REQUIRED, `powercfg /requests`). Trigger words — macos display wake-lock, iopmassertion, preventuseridledisplaysleep, pmset assertions, caffeinate, display won't sleep mac, screensaver blocked mac, screen capture assertion safari.

macOS platform companion to hd-self-screenshot — the Apple-specific half of HD screenshotting its own window, PLUS the token-efficient capture flow (`shot` — one call, prints a PNG path, never floods context with base64). The tool ladder, the `POST /screenshot` CDP endpoint, selector region-clips, the sharing gate, and the during-a-recording contention matrix live in hd-self-screenshot (adom/hd-bootstrap); THIS skill carries the `shot` helper doctrine and the macOS capture internals: the `screencapture` CLI / CoreGraphics window path, the CDP `Page.captureScreenshot` content grab, how the per-panel selector crop resolves the rect via `dom.measure` (WKWebView has no CDP) and crops with the image crate, and the Screen Recording TCC grant. Mirror of hd-self-screenshot-windows (Win32 PrintWindow/BitBlt). Trigger words — screenshot hd mac, shot helper, token efficient screenshot, screencapture cli, coregraphics screenshot, wkwebview no cdp, dom.measure crop, page.capturescreenshot mac, screen recording permission screenshot, tcc screenshot grant.

What HD's setup steps did to prepare your workspace — the 18-step install sequence that imports the Adom-Workspace golden image, injects your Adom session, wires up the relay, and walks the Claude auth gate. Use this skill when the user asks "what did setup do", "why is X installed", "re-run a setup step", "what's a virgin reset", or "why did step N fail". Trigger words — setup steps, install steps, setup panel, virgin reset, re-run step, Run All, what did setup do, why is X installed, setup failed, install-tools, hd setup, claude code extension install, hd workspace ready.

HD setup panel: 16 install steps, Run All, Rollback All, Virgin Reset with toggles, and automated testing patterns. MUST READ before running setup, testing steps, or doing virgin resets. Covers the step list, the virgin reset toggle panel, how to keep auth during resets, and how Run All handles failures. Trigger words — setup panel, install steps, run all, virgin reset, rollback, step failed, 18 steps, wipe, reset workspace, keep auth, test setup.

MUST READ before ANY HD work. Explains the three-layer topology: cloud Docker (where Claude runs), the user's Mac (where HD + Adom Desktop run), and the HD local workspace (the Adom-Workspace machine). Every command you run goes through the relay to the Mac. You CANNOT directly access the workspace machine — you must shell through the Mac. Trigger words — HD topology, cloud vs local, machine exec, nsenter, where am I, which workspace, adom-desktop relay, test from container, three tiers, architecture, mac machine.

macOS platform companion to hd-ui — the Apple-specific half of DRIVING HD's UI. Every menu/dialog/panel id, the GET /ui/actions → POST /ui/invoke contract, and registerUiAction live in hd-ui (adom/hd-bootstrap); THIS skill carries only what's macOS-specific: HD's webview is WKWebView with NO Chrome DevTools Protocol, so the legacy CDP .click() path is dead — you drive the UI via the platform-agnostic command bus (hd-ui-command → /ui/_result) and the backend invoke_ui_action RPC (e.g. dom.measure resolves a selector's rect WITHOUT CDP). Mirror of hd-ui-windows (raw CDP clicking, hd-cdp.js, WebView2 CDP). Trigger words — drive HD UI macos, WKWebView, no CDP, dom.measure, hd-ui-command, invoke_ui_action, ui/invoke macos, click HD menu mac, open dialog mac.

How HD's machine workspace storage is laid out — what's persistent, what's ephemeral, where your work lives, what survives a workspace restart vs a virgin reset, and how to access your workspace files from your Mac host. Use when the user asks "where are my files", "did I lose my work", "how do I copy a file out of the workspace", or "what happens to my code if I virgin reset". Trigger words — machine filesystem, hd volume, where are my files, workspace files, persistent storage, lost my work, /home/adom/project, machine filesystem, machine export, copy file out of workspace, where is my code, workspace backup, machine remove.

Workspace machine (`Adom-Workspace`) lifecycle management for Hydrogen Desktop on macOS. Import/export/remove/terminate, code-server-as-HD-child, the resume reality-check, recovery after sleep/hibernate, and every hard-won rule about what NOT to do — above all, NEVER run a global teardown; touch ONLY Adom-Workspace so the user's other Lima VMs / machines stay safe. MUST READ before any workspace operation. Trigger words — machine, workspace, Adom-Workspace, restart workspace, terminate machine, remove, machinectl import-tar, machinectl remove, code-server, workspace broken, workspace unhealthy, machine hung, fix workspace, /workspace/status.

How Hydrogen Desktop monitors and manages the local workspace machine (`Adom-Workspace`) and code-server. Covers the 15s workspace state poll, the two health levels (Lima VM up, machine running + code-server reachable), the floaty states (Lima VM not available, machine stopped), auto-start via setup_and_start, auto-reload of the VS Code iframe, and the lifecycle dialog system. Read BEFORE touching PanelVisualStudioCode.svelte, ContainerLifecycleDialog.svelte, or any workspace state handling code. Trigger words: workspace stopped, lima vm not available, workspace monitoring, machine poll, workspace floaty, start workspace, code-server reachable, lifecycle dialog, workspace state, Adom-Workspace running.