Project workspaces

A project can ship its Hydrogen layout. The file is hydrogen/workspace.json in the project's page repo: which panes, which tabs, which apps, arranged how. The platform side is shared with Hydrogen Cloud (the wiki validates the file, adom-cli applies and exports it, the cloud lists it). This page is about the Hydrogen Desktop side: the Project workspaces menu next to the Adom logo, what Apply, Unload and Save do on your machine, and how an AI drives all of it without a mouse.

The whole loop in 72 seconds: build a layout, save it as a project workspace, see the file, push it to the project's wiki page, then load it back three ways: from the menu, from an AI through the control API, and from a hydrogen:// link. Every step was driven through Hydrogen's API on a test box. Download the video.

Try it in two minutes

1. Clone the demo project into your workspace (in a VS Code terminal): cd ~/project && adom-wiki repo clone john/example-bench

2. Open the bench with a link. Copy this address:

   hydrogen://edit?workspace=john/example-bench
   

   Then, on a machine with Hydrogen Desktop installed, do any one of these:

   • Press Win+R, paste it, press Enter.
   • Paste it into your browser's address bar. The browser asks once whether to open Adom Hydrogen.
   • From PowerShell: Start-Process "hydrogen://edit?workspace=john/example-bench"
   • Ask your AI. It runs the same address through Adom Bridge, so you never touch the mouse.

   The wiki does not render hydrogen: links as clickable, which is why this is a copy step and not a click.

3. Hydrogen comes to the front and applies the bench next to your panes. Undo it with Unload in the Project workspaces menu, or POST /workspaces/unload from your AI.

The same three steps work for any project that ships a bench; only the reference changes.

What you see in ah

The icon right of the Adom logo opens the pulldown.

• Benches come from two places and are grouped by project, labelled "project / name": the files in your workspace checkout (hydrogen/workspace.json and hydrogen/workspaces/*.json, at ~/project and one clone folder down) and the cloud mirror, for benches the checkout does not have (tagged mirror, and legacy when they carry no project).
• Apply builds the bench from scratch: its panes and tabs, with the VS Code pane kept where it is. The tabs it closes are recorded and come back on Unload. Tick Keep my other tabs open to add the bench next to what you have instead (a tab with the same name is reused). Hydrogen Cloud applies the same way.
• Unload removes only what Apply created and stops the apps the bench started. Tabs you opened yourself, and apps the dock or another bench started, stay.
• The copy button puts the exact adom-cli hydrogen workspace apply ... command on the clipboard.
• Show me how it works runs a guided walkthrough on your desktop: the menu, Apply on an example bench, Unload, narrated, with Adom Bridge's demo panel to pause, step back or forward, mute or stop. If the checkout has no bench it fetches the example first.
• Save as project workspace exports your live layout into a project folder as hydrogen/workspace.json (or hydrogen/workspaces/<name>.json). It asks for the project reference only when the folder has no page.json. The file is written and mirrored to the cloud, not committed: commit and push it with the project as usual (adom-wiki repo push validates it).

Apply, Unload and Save run adom-cli inside your WSL2 workspace, the same binary and the same commands Hydrogen Cloud runs in a container. The command and its output stream into a launch console tab (the one the Dock Bar uses), which closes itself when the command succeeds and stays open with the reason when it fails.

The one-time offer

When a project in your checkout ships a workspace and you have not been asked about it before, ah shows one card at the top: "this project ships a workspace. Apply / Not now". It is keyed on the same preference the cloud uses (workspace.offered.<owner>.<repo>), so you are asked once across both. An unanswered card dismisses itself after a minute and counts as Not now on that machine. Nothing is ever applied on its own.

Placeholder tabs and bridges

When adom-cli cannot resolve an app (page missing, install failed, or the app needs a desktop bridge that is not connected), Apply still succeeds and the tab becomes a placeholder named "X (not available)" pointing at the app's wiki page. On the desktop that placeholder shows the Adom Bridge state with a Connect Adom Bridge button and a Re-apply workspace button; re-applying is idempotent in merge mode, so only the placeholder changes.

Driving it from an AI (no mouse)

Everything in the menu is reachable on ah's control API (port 47084 by default, the hydrogen-api skill lists every route):

curl -s http://127.0.0.1:47084/workspaces/benches | jq '.benches[].identity'
curl -s -X POST http://127.0.0.1:47084/workspaces/apply -H 'content-type: application/json' \
  -d '{"identity":"kcknox/ztest-bench-lite#hydrogen/workspace.json"}' | jq '.summary'
curl -s -X POST http://127.0.0.1:47084/workspaces/unload -H 'content-type: application/json' \
  -d '{"name":"Lite bench (example)"}' | jq '.summary'

The workspace API itself is on the local proxy (port 47083, ADOM_HYDROGEN_URL inside the workspace), and it is what adom-cli talks to: the granular routes (/current, /tabs, /splits, /moves, /swaps, /panels/{id}), GET /api/panels/catalog, the one-transaction POST .../current/apply, and .../shared forwarded to the cloud mirror. Every change to the tree carries a revision; a write based on an older revision is refused instead of overwriting someone else's change.

Skills your AI already has

• wiki-workspaces and adom-workspace-control (adom/core, shipped to every Adom user): the file format, the WORKSPACE_* hints, export and apply with adom-cli, and the pane API. These are the same on Hydrogen Cloud and Hydrogen Desktop.
• hydrogen-api and hydrogen-project-workspaces (ship with Hydrogen Desktop, installed into your workspace at setup): the /workspaces/* routes above, the menu, the offer card, and the desktop rules. These exist because the desktop exposes controls the cloud does not.

Differences from Hydrogen Cloud, on purpose

• A bench the checkout carries is applied as the local file (the copy you are editing); the wiki reference is used only for mirror-only entries.
• The desktop resolves a files-only wiki clone's project from its page slug, since page.json names the slug but not the owner.
• The desktop has no 3D editor panel: a 3d-viewer tab opens as a "not available on Hydrogen Desktop" tab. Open the same bench in Hydrogen Cloud to use it.
• hydrogen://edit?workspace=<ref|identity|path> opens or focuses ah and applies that bench once the list loads (the scheme is registered by the installer and at every start). A bench the checkout does not have gets a toast telling you to clone the project first.

Example benches

The bench from the video: john/example-bench (VS Code, the project page, the KiCad bridge page). Other throwaway examples, safe to clone and try: kcknox/ztest-bench-lite (3 tabs), kcknox/ztest-bench-kicad (6 tabs, declares the KiCad bridge), kcknox/ztest-bench (7 tabs, three dashboards).

cd ~/project && adom-wiki repo clone kcknox/ztest-bench-lite

Then open the menu (or POST /workspaces/refresh) and Apply.