Adom Bridge for macOS

A small operating system for AI on your Mac. Adom Bridge gives an AI real hands on your native desktop: your signed-in browser, KiCad, Fusion 360, the shell, files, windows, screenshots and the Accessibility tree. Bridges extend that reach to any app, and Adom Bridge provisions its own Node and Python to run them, so an add-on installs without touching your setup. It ships with Adom Hydrogen and installs standalone too, so if you drive your Mac with Claude Desktop, Claude Code, Codex or another local AI, this is what gives that AI hands.

This page is the macOS line (Apple Silicon). The Windows line lives on its own page, adom/adom-bridge; the two share one verb catalog, one relay protocol and one mesh, so a Mac and a Windows PC on the same account are peers.

• Full desktop control: windows, keyboard and mouse input, screenshots, the Accessibility tree (background clicks that never steal focus), the shell, files, processes, notifications.
• Bridges: first-class mini-apps. Puppeteer (browser), KiCad, Fusion 360, your real signed-in browser, Blender, or your own.
• You are in control: loopback-only, an install-consent trust model, an activity log, and a human-only approval gate for anything that arrives from the cloud.
• Multi-machine: address any of your machines by name over the relay, or reach it directly over the Adom Mesh, end-to-end encrypted between your own boxes.
• Signed and self-updating: every release is Developer ID-signed, notarized, SHA-256-verified, and the app updates itself from this page.

How it works

The cloud AI never touches your Mac directly. It sends a verb to the relay; Adom Bridge, connected out to that relay from your Mac, executes it or forwards it to a bridge, and streams the result back. A co-resident app (Adom Hydrogen, or a local AI's CLI) skips the relay and POSTs straight to the loopback HTTP API on 127.0.0.1. Another of your own machines can reach this one over the mesh without going through the cloud relay at all.

Adom container (this package)            Your Mac
+--------------------------+             +--------------------------------+
| adom-bridge CLI + skills |  <-relay->  | Adom Bridge.app (menu-bar agent)|
| (the AI drives verbs)    |             | KiCad, Fusion, Chrome, shell,   |
+--------------------------+             | files, screens, notifications   |
                                         +--------------------------------+
                                                   ^  mesh (QUIC, e2e encrypted)
                                                   v
                                         +--------------------------------+
                                         | your other Macs / Windows PCs   |
                                         +--------------------------------+

• Two binaries. The app is the automation surface on the Mac. The CLI (adom-bridge) is the caller: on the same Mac it uses the loopback API, from a container it routes the same verbs over the relay.
• Bridges are separate processes the app spawns and supervises. Each owns a verb prefix (browser_*, kicad_*, ...) and a small HTTP endpoint; the app relays verbs to it verbatim and reports its health.
• Verbs return identical JSON on every path (relay, loopback, CLI, mesh): the same _hint, errorCode and status fields, so a caller writes the code once.

Install on the Mac

Requirements: macOS on Apple Silicon.

One line (downloads the signed DMG from this page, verifies its SHA-256, installs to /Applications, launches):

curl -fsSL https://wiki.adom.inc/api/v1/pages/adom-bridge-macos/files/install.sh | sh

Or download the DMG from the Download for your machine box and drag Adom Bridge.app to Applications. Adom Hydrogen users do neither: Hydrogen installs and manages Bridge automatically.

First run shows the sign-in window. After that Bridge is a menu-bar agent: no window, no Dock icon, launched at login by a LaunchAgent. Double-click the app (or use the menu-bar item) to summon the window for settings, approvals and sign-in; closing it or pressing Cmd-Q hides it again rather than stopping the agent.

macOS permissions. Bridge is the single TCC identity for everything it drives. It asks for Screen Recording the first time a screenshot is requested, Accessibility the first time a background UI click is requested, and Full Disk Access only when a caller needs a protected folder. Nothing is requested at install. desktop_permission_status reports all three.

Uninstall: quit from the menu bar, then adom-bridge uninstall from the bundled CLI (removes the LaunchAgent) and drag the app to the Trash. Your sign-in lives in the shared keychain item and survives a reinstall.

Install in a container (this package)

adom-wiki pkg install adom/adom-bridge-macos

This installs the container-side pieces: the Claude skill set that teaches an AI every desktop verb, and the Linux adom-bridge CLI when one is staged with the release. Not needed under Adom Hydrogen, which wires its container to Bridge itself. adom-wiki pkg update keeps it current.

The KiCad and Fusion 360 bridge skills install from their own pages: adom-bridge-kicad-bridge and adom-bridge-fusion-bridge-macos.

Drive it from a local AI on the same Mac

You do not need the cloud. The app bundles its CLI at Adom Bridge.app/Contents/Resources/adom-bridge-cli and, on every launch, copies its skills into ~/.claude/skills and ~/.codex/skills, so Claude Desktop, Claude Code or Codex on the same Mac can drive the desktop with no relay and no setup. Local callers talk to the loopback API and are trusted by transport: no approval prompts.

Sign in once, connect everywhere

Sign in to your Adom account in the app and your cloud containers connect automatically: no JSON, no copy-paste. The session is one keychain item shared with Adom Hydrogen, so signing in to either app signs in both, and it survives uninstall and reinstall. An AI in a container registers its relay with one verb (server_add).

Under Adom Hydrogen

When Adom Hydrogen launches Bridge it runs embedded: hidden, with Hydrogen owning the sign-in, the updates and the permission dialog. Gated commands from the cloud show up as a card in Hydrogen's own approval dialog; your choice there (allow once, 1 hour, 24 hours, bypass, deny) applies to Bridge. If Hydrogen ever goes away, Bridge reverts to standalone so your Mac stays reachable.

Staying current

Bridge polls this page's version.json on launch and every 4 hours. A new release downloads as a DMG, is SHA-256-verified against the manifest, and is applied silently: mount, swap the app bundle, relaunch. Your preference is Prompt (default), Auto or Off in Settings; a release can also carry a priority that overrides Prompt for a recommended fix or forces an emergency update. Embedded under Hydrogen, Hydrogen owns the update timing.

Screenshots on macOS

Anything on screen can be captured without stealing focus: desktop_list_windows enumerates windows (the hwnd field carries the CGWindowID, same arg name as the Windows line), desktop_screenshot_window {hwnd | titleContains} captures one window with its chrome, desktop_screenshot_screen captures the main display, desktop_list_monitors enumerates displays. Everything the window and input verbs speak is in points, one coordinate space, so a rect from desktop_list_windows can be passed straight to desktop_click {x, y}. Captures need the Screen Recording permission; until it is granted the response says permission_required instead of returning an empty list.

Not on macOS: owned-popup arrays, per-monitor screenshots and the image-space coordMap. Recording a browser tab is the Puppeteer bridge's own feature.

Screen recording

desktop_record_start records a whole display or one window to an MP4 (1.9.229+): ScreenCaptureKit capture, H.264 High or HEVC Main on the Apple media engine, the system audio mix as AAC, cursor on or off, and VBR, CBR or constant-quality rate control. A window take records the window itself, so it keeps recording when the window is covered or moved. Stop with desktop_record_stop and pull the file with pull_file; macOS shows its screen-recording indicator in the menu bar for the whole take.

Background UI automation

The desktop_ui_* family is backed by the macOS Accessibility API: desktop_find_control {hwnd, name|contains} returns a control's on-screen rect, desktop_ui_click presses it via AXPress and desktop_ui_set sets its value, all in the background. desktop_mouse_click posts a click to a specific process without raising it. Every response carries a measured foreground block saying whether anything was raised, never an assertion. Synthetic foreground input (desktop_click, desktop_type, desktop_press_key) uses CGEvent and rides the same approval grant as the shell.

Bridges

Each bridge is a small, independently versioned process the app spawns, supervises, health-checks and updates from its own wiki page. A bridge whose page declares macOS unsupported is never run; the bundled build is used instead.

Install a third-party bridge with bridge_install {"manifestUrl": "..."}. Bridge provisions a managed Node and Python for bridges that need them, with no admin prompt. Build your own with the Bridge SDK.

Security and the approval gate

The trust boundary is install-consent plus the loopback bind. Installing Bridge (and each bridge) is you granting permission for the AI to drive your Mac; if you do not want that, uninstall. The app and every bridge bind 127.0.0.1 only, so a caller must already be a program you installed on your own machine to reach it.

On top of that, the remote path is approval-gated. Verbs that run code or change the machine (shell_execute, run_script, launch_process, write_file, delete_file, process_kill, synthetic input and Accessibility actions) require a human grant when they arrive over the relay or the mesh: 1 hour or 24 hours (time-boxed), Bypass (until revoked), or Deny. Every gated call must carry a reason, shown to you verbatim. The grant is human-only: the AI can surface the prompt (request_shell_approval) but can never grant it to itself. Read-only verbs are never gated. Under Hydrogen the prompt is Hydrogen's permission dialog; standalone it is the Bridge window and a notification.

Notifications

notify_user fires a native Notification Center notification under Adom Bridge's own identity, from a cloud AI, a bridge, or another of your machines. Buttons round-trip: "wait": true blocks until you click and returns your choice, or the AI drains clicks later with notify_events. focus makes a click reveal a window on your screen (Hydrogen, a browser waiting on a login). Progress bars and inline text fields from the Windows line do not exist in Notification Center; the verb ignores what the platform cannot render and the response says so.

adom-bridge notify_user '{"title":"Ship v2?","buttons":[{"label":"Ship it"},{"label":"Hold"}],"wait":true,"timeoutSec":120}'

Many machines: the relay and the Adom Mesh

One relay can hold many Bridges. Address any of them by name, or fan out:

adom-bridge targets                                   # every machine the relay or the mesh knows
adom-bridge --target kbergss-Air desktop_screenshot_screen
adom-bridge --target all bridge_list

Since 1.9.219 the Mac line also runs the Adom Mesh. Each box mints an ed25519 node key, publishes its public identity to your account's directory, and --target tries the mesh first: an end-to-end encrypted QUIC connection between your two boxes, carried through the Adom mesh relay when they are on different networks, direct on a LAN in direct mode. A mesh answer carries route.via: "mesh". When a target is not on the cloud relay, the relay hands the call to a connected Bridge to carry over its mesh. Files move the same way: desktop_mesh_pull_files pulls SHA-256-verified over the mesh path.

• Off by default. desktop_mesh_set_mode {"mode":"relay"} turns it on; direct adds a LAN socket.
• Trust is per box: after first start a new node is refused both ways until a human trusts it. desktop_mesh_trust lists, raises, revokes and denies by verb; it never approves.
• desktop_mesh_status and desktop_mesh_peers show identity, relay state, trust and the path each peer selected.
• Both machines have to be awake and connected: a sleeping Mac is not on the mesh.
• A Windows Bridge 2.1.40 or later on the same account is a full peer.

Deep dive: the adom-bridge-mesh-macos skill on this page.

Verbs

Bridge core owns the generic verbs (desktop_*, shell, files, notify_user, multi-machine, mesh). Each bridge owns its prefix. Invoke the same way on every transport:

adom-bridge commands                                        # the live catalog, run this first
adom-bridge desktop_screenshot_window '{"titleContains":"KiCad"}'
adom-bridge shell_execute '{"command":"git status","reason":"Checking the working tree"}'
curl -s -X POST 127.0.0.1:47200/command \
  -d '{"app":"desktop","command":"notify_user","args":{"title":"Hi"}}'   # loopback API

The loopback port is 47200 (it may walk to 47209; ~/.adom/direct-api-port says which). GET /commands on it is the same catalog.

What is on this page

Source: adom-inc/bridge-macos on GitHub (the macOS line; the Windows line is adom-inc/adom-bridge).