main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-bridges description: >- Bridges from a Linux Hydrogen workspace: the KiCad, Fusion 360 and Puppeteer bridges and the wiki bridge catalog, all served by Adom Bridge on a desktop, how to tell which machine has them, and bridge status. Use when asked about bridges, bridge status, install a bridge, or drive KiCad, Fusion or pup.

Hydrogen bridges (Linux)

Bridges are small local servers that Adom Bridge (ab) runs on a desktop machine: kicad_*, fusion_*, pup_* and the catalog bridges. The workspace reaches them with the adom-bridge <verb> CLI through the relay at ws://127.0.0.1:8765.

Hydrogen for Linux installs and runs ab when a Linux build is published for the user's account (see hydrogen-embedded-bridge). So on this desktop:

  • With no ab running here (none published for the account yet), bridge verbs reach only the user's OTHER machines on the Adom mesh (adom-bridge --ai-thread "<thread>" targets, then --target <name>). For KiCad or Fusion on the user's Windows PC, that is the normal route. Never guess which machine: ask.
  • With ab running here, bridges that have a Linux build run locally; bridges without a Linux build are listed but answer unsupported_on_this_os. Fusion 360 has no Linux build.

The examples below leave out --ai-thread and --target; add them as above.


Bridge Architecture

Adom Bridge launches bridge processes on demand on its machine. This is an extensible ecosystem, not a fixed list: new bridges ship via the wiki catalog (see "Extensible bridge catalog" below). The core/first-party bridges:

Bridge Display name Port (default) Target app Description
kicad-bridge KiCad Bridge 8771 KiCad Control KiCad PCB editor from Adom containers
fusion-bridge Fusion 360 Bridge 8773 Fusion 360 Control Fusion 360 CAD/CAM and EAGLE PCB
puppeteer-bridge Puppeteer Bridge 8851 Chrome for Testing Chrome automation, screenshots, and recording

Bridge ports have conventional defaults (KiCad 8771, Fusion 8773, Pup 8851), but adom-bridge registers the live port at bridge launch and may pick a different one if a default is taken. To find the actual live port, run adom-bridge status and look at desktop.apps.<bridge>.bridgePort (or adom-bridge bridge_list). In practice you don't need the port directly — use the adom-bridge <verb> CLI which routes to the right bridge automatically.

Bridges are launched on demand. They are NOT always running. There is no Bridge Manager dialog in Hydrogen for Linux; ask ab (adom-bridge status or adom-bridge bridge_list).

What Adom Bridge can do (live capability list)

Bridges are only part of ab. Query the authoritative, machine-specific list:

adom-bridge status   # → .capabilities  and  .desktop.apps

On a typical machine .capabilities = notify, files, kicad, fusion360, shell, usb, screenshot, browser, caption, record. Mapping to where each is documented:

capability what it is skill
kicad / fusion360 / browser the three built-in app bridges this skill
screenshot / record / caption OS screenshots, screen/tab recording, recording captions this skill (screenshots/recording); caption is recording-caption support
files send_files / pull_file hydrogen-file-transfer, hydrogen-adom-bridge
notify desktop toast notifications this skill
shell run a command on the user's PC (approval-gated) hydrogen-adom-bridge

.desktop.apps also reports, per app: bridgeRunning, installed, running, version — use it to check whether the target app (KiCad/Fusion/Chrome) is present before driving its bridge.


Prerequisites

Check connection: adom-bridge --ai-thread "<thread>" targets lists the machines whose ab is connected to the relay. On this desktop Hydrogen installs and starts ab when a Linux build is published for the user's account (see hydrogen-embedded-bridge); if none is connected, the setup step ensure-adom-bridge-cli and the [ab-linux] log lines say why.


Screenshots (zero dialogs, instant)

# Full screen capture
adom-bridge desktop_screenshot_screen

# Resized for Claude vision (default to this)
adom-bridge desktop_screenshot_screen '{"maxWidth": 1500}'

# Specific window by HWND
adom-bridge desktop_screenshot_window '{"hwnd": 12345}'

# List all capturable windows
adom-bridge desktop_list_windows

AI guidance:

  • Default to maxWidth: 1500 -- Claude vision hard limit is 2000px
  • Use format: "png" for UI/text (default, lossless)
  • Use format: "jpeg", quality: 80 for photos/3D renders
  • Use format: "webp" for smaller file sizes

Browser Automation (Puppeteer Bridge)

Port: default 8851 (adom-bridge registers the live port; see adom-bridge status). Auto-downloads Chrome for Testing if not present.

# Open browser window
adom-bridge pup_open_window '{"url": "https://example.com"}'

# Screenshot current tab
adom-bridge pup_screenshot '{"sessionId": "default"}'

# Evaluate JavaScript
adom-bridge pup_eval '{"js": "document.title", "sessionId": "default"}'

# Navigate
adom-bridge pup_navigate '{"url": "https://...", "sessionId": "default"}'

# List open windows/tabs
adom-bridge pup_list_windows

# Record tab (CDP screencast, zero dialogs)
adom-bridge pup_record_start '{"sessionId": "default"}'
adom-bridge pup_record_stop '{"sessionId": "default"}'

KiCad Bridge

Port: default 8771 (adom-bridge registers the live port; see adom-bridge status). Requires KiCad to be installed on the user's machine.

adom-bridge kicad_open_board '{"path": "<host path to board.kicad_pcb>"}'
adom-bridge kicad_open_schematic '{"path": "<host path to schematic.kicad_sch>"}'
adom-bridge kicad_open_3d_viewer
adom-bridge kicad_run_drc '{"path": "..."}'
adom-bridge kicad_screenshot_all
adom-bridge kicad_window_info
adom-bridge kicad_send_key '{"key": "ctrl+s"}'
adom-bridge kicad_list_versions
adom-bridge kicad_install_symbol '{"path": "/tmp/symbol.kicad_sym", "library": "MyLib"}'
adom-bridge kicad_install_library '{"path": "/tmp/footprints", "name": "MyFootprints"}'

Always run kicad_window_info BEFORE any KiCad operation to check for modal dialogs — and AFTER any save/DRC/open to catch errors KiCad raised.

Finding + reading KiCad errors (modal dialogs)

kicad_window_info returns hasModalDialogs (bool) + a modalDialogs array — this is how you detect a KiCad error/blocking dialog (a save-permission error, a file-format warning, a DRC blocker). Each entry is {hwnd, ownerHwnd, title} (e.g. title:"Error"):

adom-bridge kicad_window_info '{}'
# → { editors:[...], hasModalDialogs:true,
#     modalDialogs:[{ "hwnd":200934, "ownerHwnd":6163368, "title":"Error" }], projectManager:{...} }
  • ⚠️ modalDialogs gives the title + hwnd, NOT the body text. To read what the error says, screenshot the dialog by its hwnd: adom-bridge desktop_screenshot_window '{"hwnd":200934}' → read the saved PNG. (Verified live 2026-06-15: a ctrl+s on a read-only board surfaced hasModalDialogs:true + a title:"Error" entry; screenshotting its hwnd read "Insufficient permissions to save file …".)
  • Dismiss it before proceeding: kicad_send_key '{"hwnd":<dialog hwnd>,"key":"return"}' (OK) or "escape" (Cancel). A lingering modal blocks every subsequent KiCad action.
  • So the loop is: operate → kicad_window_info → if hasModalDialogs, screenshot each modalDialogs[].hwnd to read it → handle/dismiss. Don't assume an operation succeeded just because the verb returned success:true — KiCad can still pop a blocking error.

Fusion 360 Bridge

Port: default 8773 (adom-bridge registers the live port; see adom-bridge status). Requires Fusion 360 to be installed on the user's machine.

adom-bridge fusion_start
adom-bridge fusion_import_step '{"path": "<host path to model.step>"}'
adom-bridge fusion_export_step '{"path": "<host path to output.step>"}'
adom-bridge fusion_board_info
adom-bridge fusion_electron_run '{"command": "..."}'

Extensible bridge catalog (bridges are NOT a fixed set)

Bridges are a growing ecosystem. The three above (KiCad / Fusion 360 / Puppeteer) are built into Adom Bridge. Additional bridges are published to the wiki bridge catalog and installed on demand — for example the Blender bridge (adom-blender-bridge), which is NOT built in (it won't appear in adom-bridge status until installed). To use a catalog bridge:

  • Discover: the wiki catalog at /apps?tag=hydrogen-bridge.
  • Reserved ports: the 8900-8999 range is set aside for 3rd-party bridges.
  • Enumerate what's actually live: adom-bridge status → desktop.apps.* lists every bridge ab currently knows about, with bridgePort, status, and whether the target app was detected. Treat that as the source of truth for "what bridges exist right now" — this skill's table lists the core ones, but new catalog bridges will appear in status without being in this table.
  • Invoke any bridge through the adom-bridge <verb> CLI; it routes to the right bridge automatically (you rarely need the port directly).

Maintainer note: keep this skill in sync by periodically running adom-bridge status against a fully-bridged machine and reconciling the table.


File Transfer

# Send a file from the workspace to the desktop
adom-bridge send_files '{"filePaths":["/home/adom/project/out.pdf"],"saveTo":"<folder on that machine>"}'

# Pull a file from the desktop to the workspace (remotePath uses that machine's native path convention)
adom-bridge pull_file '{"remotePath": "<host path to data.csv>", "localPath": "/tmp/data.csv"}'

Desktop Interaction

# Toast notification
adom-bridge notify_user '{"message": "Build complete!", "duration_ms": 5000}'

# Open URL in user's browser
adom-bridge desktop_open_url '{"url": "https://..."}'

# Open folder in the OS file manager
adom-bridge desktop_open_folder '{"path": "<host folder path>"}'

# Execute shell command in the host's native shell (requires user approval)
adom-bridge shell_execute '{"command": "<host shell command>"}'

Screen Recording

Served by Adom Bridge. The desktop_record_* / desktop_recorder_* verbs exist only when the target machine's ab offers them. Verify before using: adom-bridge status, then .capabilities must include record. See hydrogen-recording for full details.

Tab-vs-desktop footgun. desktop_record_start records the whole screen and requires an explicit confirmDesktopNotTabRecording:true guard so you don't accidentally capture the entire desktop when you meant one tab. To record a single Chrome tab, use pup_record_start instead (CDP screencast, served by the Puppeteer bridge, no whole-screen capture).

# Record entire desktop (ab-served; needs the confirm guard, zero dialogs)
adom-bridge desktop_record_start '{"reason": "Demo recording", "confirmDesktopNotTabRecording": true}'
adom-bridge desktop_record_stop

# Record a single browser tab (CDP screencast, zero dialogs) — prefer this for one tab
adom-bridge pup_record_start '{"sessionId": "default"}'
adom-bridge pup_record_stop '{"sessionId": "default"}'

Ralph Loop Pattern

# 1. Take screenshot
adom-bridge desktop_screenshot_screen '{"maxWidth": 1500}'
# 2. Read the screenshot (it's saved to /screenshots/)
# 3. Analyze with Claude vision
# 4. Make changes
# 5. Take another screenshot
# 6. Repeat until done

Browser Profiles

Hydrogen can detect all browser profiles installed on the user's machine and open URLs in specific browsers/profiles.

Control API endpoints:

  • GET /browser-profiles -- detect Chrome, Edge, Brave, Firefox, Opera profiles
  • POST /open-in-profile -- open URL in a specific browser and profile
  • POST /open-url -- open URL in the default browser

On Linux the profiles are found from PATH, snap, Flatpak and Firefox profiles.ini (Chromium and Vivaldi are detected too). None of this needs ab. See hydrogen-browser-picker.

Source: src/lib/components/BrowserProfileDialog.svelte


Cross-references

  • hydrogen-adom-bridge-triage -- ab will not connect
  • hydrogen-embedded-bridge -- how a Linux ab and Hydrogen relate
  • adom-bridge-multi-machine -- --target, targets, primary_machine
  • adom-bridge-linux -- running ab on this Linux desktop
  • kicad-bridge -- the KiCad bridge's own skill
  • hydrogen-networking -- port architecture (conventional bridge ports + dynamic registration)
  • hydrogen-adom-menu -- the API Explorer (has bridge-related endpoints)
  • hydrogen-settings -- Hydrogen settings surface
  • hydrogen-self-screenshot -- host screenshots, window control, and the ralph loop
  • kicad-interaction -- foundational KiCad desktop interaction rules
  • pup -- Puppeteer browser control via pup CLI