Adom Bridge (macOS)

The Adom Desktop companion app for macOS (Apple Silicon). Use when a Mac user needs Adom Desktop installed, updated, or checked — the dmg ships via this page's releases and version.json; Adom Hydrogen's setup installs it automatically.

Sign in to Adom Bridge and connect a cloud container to the user's Mac: the Connections panel 'Sign in to Adom' browser flow, the shared macOS keychain session (one sign-in serves Bridge and Adom Hydrogen), auto-discover servers from the user's Adom Cloud profile (zero JSON paste), register_container from a cloud container, the one-command setup_desktop flow, the cloud key-value config keys (desktop.container.*), the paste-JSON fallback, and sign-out. Trigger words: sign in to Adom Bridge, connect container to desktop, register_container, setup_desktop, auto-discover servers, connect my desktop, server JSON, cloud config, sign out, keychain session.

The boundary between Adom Bridge core and a bridge author — what AD owns vs what you (the bridge) own. Read before filing an AD bug about a bridge (kicad, fusion360, native-browser, puppeteer, blender, rdp, or any third-party bridge) or before editing bridge code, so you fix and report in the right place.

Author, PUBLISH, and make-discoverable an adom-desktop bridge — a small local server that adds a namespace of verbs (kicad_, fusion_, browser_, your_prefix_) to adom-desktop. Use when building, publishing, updating, prewarming, or debugging a bridge, or deciding what skills to ship. Covers the AD-core-vs-author boundary; the #1 rule (rich hints in EVERY verb's OUTPUT, because the AI reads CLI output, never your on-disk skill); bridge.json; where every file lives (the Release-zip-vs-skills-pkg split, the TWO package.json files [server deps in the zip; the pkg declares dependencies:{adom/adom-desktop}], manifest + runtime-asset placement); the pkg carries ONLY user skills while dev + publish skills live in your source repo (not the pkg); the THREE things you publish (runtime Release zip + manifest, container skills pkg, wiki discovery_triggers); prewarm; and the auto-discover → install-check → use flow.

Consumer guide to Adom Bridge bridges: what a bridge is, the Bridges sidebar cards, bridge status and the bridge LED colors (green/yellow/red/gray), bridge lifecycle (spawn, stable port, single instance, auto-respawn, duplicate collapse), how to install a bridge (bridge_install with a manifestUrl), bridge updates (refresh_bridges, bridge_check_updates, the 4-hour auto-sync from each bridge's wiki page), the bridge console and logs (bridge_log_read and the lifecycle log), bridge management verbs (bridge_list, bridge_info, bridge_detail, bridge_kill, bridge_pause, bridge_resume, bridge_readiness), and sync_skills for pulling each bridge's own skill package. Trigger words: bridge status, bridge LED, install a bridge, bridge_install, refresh_bridges, bridge console, bridge lifecycle, sync_skills, bridge updates, bridge_list, bridge_kill, bridge stuck, bridge offline, bridge not running.

Use when working with the adom-desktop CLI itself - how to run desktop verbs, discover commands (adom-desktop commands, help topics), address targets with --target, start the serve relay with --supervise, read the status/durationMs/timeoutSeconds response shape, stream long ops with watch, or sweep the screenshot cache with janitor.

Direct HTTP API on the Adom Bridge app. Use when authoring a sibling app (Adom Hydrogen, future Adom-family apps) on the same Mac that needs to send commands into Adom Bridge without spawning the CLI binary or going through the WebSocket relay. Local-only (loopback bind).

Reaches the user's Mac desktop from this container via Adom Bridge (CLI: adom-desktop). Run commands and scripts on the Mac, list/kill processes, restart apps, desktop and app-window screenshots, send/pull files, notifications, list/focus windows. Also launches and drives KiCad (schematics/boards/symbols/footprints, DRC, library install, 3D viewer, automation) and Fusion 360 (.f3d/.f3z, import/export STEP/GLB/.lbr, BOM/parameters, Fusion API). Also covers Puppeteer/pup real-Chrome automation (browser_screenshot, browser_eval, browser_navigate, multi-session profiles, ralph-loop), the relay server (adom-desktop serve), and connection setup. Trigger words: run command on laptop, run on my mac, restart a program, kill a process, list processes, screenshot laptop/desktop/mac/fusion/kicad, list windows, focus window, send file to laptop, pull file from laptop, desktop notification, launch KiCad, open in KiCad, run DRC, launch Fusion, import/export STEP, export GLB/lbr, Fusion API, pup, puppeteer, real Chrome, browser automation, open URL on desktop, adom bridge, adom-desktop, bridge to my mac, KiCad bridge, Fusion bridge.

Adom Bridge's EMBEDDED mode under Adom Hydrogen - what it means when Hydrogen owns Bridge, the lifecycle contract (Bridge stays up; exit when Hydrogen exits is opt-in flag-only), embedded permissions (Hydrogen's auto_approve on /embedded/enter, forwarding gated commands to Hydrogen's /permission/request, status.permissions.shell.embeddedPolicy), inspecting Hydrogen with hd_status and the hd_ verb family, and the read-only Hydrogen-managed relay entry. Use when reasoning about embedded vs standalone behavior, why Bridge survived (or should survive) a Hydrogen crash, why a gated command is waiting on Hydrogen instead of showing a Bridge dialog, or how to drive/inspect Hydrogen from a cloud caller.

Drive this Mac from a LOCAL AI tool (Claude Desktop, Claude Code, Codex, or any agent running on the same machine) through Adom Bridge's bundled CLI, adom-desktop-cli. No relay, no cloud container, no --target. Use when the user says "Claude Desktop, control my Mac", "use Adom Bridge from Claude Code on my Mac", "local AI, drive my desktop", or when you find the bundled adom-desktop-cli. Covers the bundled CLI, the auto-linked consumer skills, loopback direct-API routing, and a starter verb cookbook.

Address and fan out to multiple Adom Bridges on one relay. Use when more than one machine runs Adom Bridge on the same relay and you need to target a specific one (--target <name>) or broadcast to all (--target all), e.g. a Mac laptop plus a second desk machine. Covers client naming, --target, the targets verb, stable-identity eviction, and ambiguous-target handling.

Send native macOS Notification Center notifications from a cloud AI or a bridge via Adom Bridge's notify_user verb, and GET THE USER'S ANSWER BACK. Two separate axes: (1) get the reply to you (wait:true blocks and returns their choice, or poll notify_events/notify_response; there is no server-push to a turn-based AI). (2) reveal a window on their screen with `focus`, a local desktop action, including focus:{host:true} to reveal Adom Hydrogen when Bridge is embedded, and focus:{app} for any app. Use to alert the user (build done, export ready), point them at a window that needs them, or ask for a decision and read it back. Covers the notification types, the exact verb calls, how the AI polls or waits for responses, and what a click actually does.

How the Adom Bridge human-approval permission gate works for an AI caller. Read this when a verb refuses with errorCode needs_approval or reason_required, when you need shell approval / bypass permissions on a machine, when you must call request_shell_approval to surface the human approval dialog, when a call demands a reason arg, or before an unattended run that touches shell_execute, run_script, write_file, or any other gated verb. Covers the human approval gate, the Approve 1 hr / 24 hr / Bypass Permissions buttons, why grants are human-only, and the macOS TCC permissions (Screen Recording, Accessibility) that sit underneath Bridge's own gate.

How Adom Bridge lives quietly on a Mac. Covers the menu-bar agent model (signed-in launches go straight to the menu bar with no window and no Dock icon), summoning the window from the menu-bar item, close-to-menu-bar behavior (the close button hides the window, Bridge keeps serving), launch at login via LaunchAgent (default ON, self-healing), the shared Adom sign-in in the keychain, and the window title markers. Use when a user or AI asks why Bridge is still running after closing the window, where the app went after launch, why there is no Dock icon, how to enable or disable launch at login, why the menu-bar item is missing, or what the window title markers mean.

Managed Node and Python runtimes for Adom Bridge bridges on macOS. Use this skill when a node or python bridge fails to spawn, when you need to check runtime status with the runtimes verb, when a bridge needs Node.js or Python and the box may not have one, when npm dependencies for a source-only node bridge are missing, or when you want to understand the no-elevation portable node/python install, the prewarm on first launch, the Runtimes panel in the GUI, or the loopback-only bind rule for bridge processes.

The complete reference for Adom Bridge screenshots on macOS: every capture verb, the exact JSON response shape, and how the CLI automatically stores each shot on disk (the window/ and screen/ buckets, the ISO-stamped filenames, the single-vs-full/safe pair, and the <stem>.json sidecar). Read this to capture an app window without stealing focus, to grab the screen, to understand the Screen Recording permission requirement, or to build a tool (like shotlog) that renders every screenshot shape Adom Bridge can return. Covers desktop_screenshot_window, desktop_screenshot_screen, kicad_screenshot_all, desktop_find_window, desktop_list_windows, desktop_list_monitors, and the exact on-disk sidecar schema.

Use when the user wants to send files to their Mac, control KiCad or Fusion 360, send desktop notifications, or troubleshoot the Adom Bridge connection. Provides CLI tools for bridging the Docker container to the user's local machine. The CLI binary is still named adom-desktop.