adom-desktop --version          # path + version, e.g. adom-desktop 1.9.x (<sha>, built ...)
adom-desktop ping               # {echo:"pong", status:"connected"} == the Mac is reachable

adom-desktop commands            # full verb catalog (categories, verbs, args/returns)
adom-desktop status              # desktop state (installed apps, bridges, ...): also surfaces the catalog

adom-wiki pkg install adom/adom-desktop   # installs the adom-desktop CLI + the adom-desktop-* skills
adom-desktop --version                    # confirm

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

---
name: adom-desktop-discovery
user-invocable: false
description: "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: discovery & install

**This skill is a pointer.** Adom Bridge (formerly Adom Desktop) runs on the user's Mac; the CLI you drive it with is still named `adom-desktop`. When any trigger fires, confirm the `adom-desktop` CLI is installed (install from the wiki if not), make sure the relay is up, then **discover the exact verb at runtime**. Do NOT guess from memory and do NOT rely on `--help`.

## 1: Check it's installed + the relay is up

```bash
adom-desktop --version          # path + version, e.g. adom-desktop 1.9.x (<sha>, built ...)
adom-desktop ping               # {echo:"pong", status:"connected"} == the Mac is reachable
```

If `adom-desktop` isn't found: see section 4, install. If `ping` doesn't say `connected`, the relay isn't serving. Start it with `adom-desktop serve --supervise` (v1.9.168+: detaches and self-heals so it survives your session; a plain `serve &` dies when the session is torn down and leaves every connected desktop in a reconnect loop). Then re-run `ping`.

### Connecting a desktop for the FIRST time: run `setup_desktop`, don't hand-build JSON

If no desktop is connected yet (`adom-desktop targets` shows none) and you need to set one up, **run `adom-desktop setup_desktop`** (aliases: `connect`, `setup`, `connect_info`). It auto-detects this container's public relay URL and hands you everything. **Do NOT assemble the connection JSON yourself**: guessing the URL and fields is the number one setup failure.

**PREFERRED: zero paste (the modern path):** `setup_desktop` returns a ready-to-run **`register_command`**. Run it. It is `adom-desktop register_container` with the name and URL filled in, and it writes this connection into the **user's Adom account** (their cloud profile). Then the user just installs Adom Bridge on their Mac and signs in with their Adom account, and the connection appears in their list and auto-connects, no JSON paste at all. (`register_container` needs an Adom cloud container; it uses the mounted account token and returns `ok:false` on a non-Adom box.)

**FALLBACK: paste-JSON:** if `register_container` returns `ok:false` (not an Adom cloud container, or the user won't sign in), have the user paste the `server_config` JSON that `setup_desktop` returned into Bridge's Connections panel, "Paste server JSON to add" box.

Either way, start the relay here so the desktop has something to dial: `adom-desktop serve --supervise`. Verify with `adom-desktop targets`.

## 2: DISCOVER THE VERB: `adom-desktop commands` (NOT `--help`)

This is the step that's most often skipped, and skipping it is why calls get hand-rolled with `shell_execute` and fumble. **`adom-desktop --help` only lists `serve` / `install`**: every real capability is a *dynamic verb* forwarded to the Mac, and the authoritative, machine-readable catalog (200+ verbs, each with args + return shape + a `_hint`) is:

```bash
adom-desktop commands            # full verb catalog (categories, verbs, args/returns)
adom-desktop status              # desktop state (installed apps, bridges, ...): also surfaces the catalog
```

**Always check `commands` before reaching for `shell_execute`.** There is almost certainly a structured verb that takes typed args, so you never hand-quote a command through JSON into a shell. A few you'll want often:

| Want to... | Use (structured: no quoting) | NOT |
|---|---|---|
| list processes | `process_list {"nameContains":"Finder"}` | `shell_execute "ps aux \| grep ..."` |
| kill a process | `process_kill {"name":"Dock"}` (or `{"pid":N}`) | `shell_execute "kill ..."` |
| start an app | `launch_process {"path":"/usr/bin/open","args":["-a","Safari"]}` / `launch {...}` | `shell_execute "open ..."` |
| run a multi-line / quoted script | `run_script {"interpreter":"bash\|zsh\|sh","scriptB64":"<base64>"}` | `shell_execute` with nested quotes |
| screenshots / windows | `desktop_list_windows`, `desktop_screenshot_window {"hwnd":N}`, `desktop_find_window`, `desktop_bring_to_front` | - |
| move files | `send_files` (to the Mac), `pull_file` (from the Mac) | - |

> **Example: "the Dock is acting up, restart it":** `process_kill {"name":"Dock"}` (macOS respawns the Dock automatically), then `process_list {"nameContains":"Dock"}` to confirm. No shell quoting. (`shell_execute` is the escape hatch for things with no verb yet; reserve it for that.)

**Reading any result:** every verb returns a uniform **`status`** (`ok` | `timeout` | `busy` | `error`) + **`durationMs`**, alongside `exitCode`/`stdout`/`stderr` for exec verbs. So an empty `stdout` with `status:ok` is a real empty-output success, NOT a timeout. `timeout`/`busy` carry a recovery `_hint`. Multi-machine relay: if you get `status:error` / `ambiguous_target`, pass `--target <name>` (list them with `adom-desktop targets`).

## 3: Long-running operations

For any multi-minute command, prefer verbs that return immediately and let you poll: `launch_process` with `detached:true` for a long-running process, and the `watch` wrapper for the whitelisted long walks (see the CLI guide skill). A sync call that outlives its `timeoutSeconds` budget returns `errorCode:"timed_out"` with `stillRunning:true`; poll the response's `statusVerb` instead of re-issuing.

## 4: Install (if missing or stale)

The canonical container install is the wiki package (bundles the Linux CLI **and** the skill set, which link into `~/.claude/skills/`):

```bash
adom-wiki pkg install adom/adom-desktop   # installs the adom-desktop CLI + the adom-desktop-* skills
adom-desktop --version                    # confirm
```

`adom-desktop status` reports the latest published version; if your local CLI is older, re-run the pkg install to refresh the binary **and** the skills atomically. **If you hand-installed only the binary, you won't have the skill set: re-run the pkg install so the discovery/main/direct-api skills land too.**

The user's Mac app installs separately (Apple Silicon, notarized dmg):

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

On machines running Adom Hydrogen, Hydrogen installs and manages Bridge automatically; no manual install needed.

## 5: What you get once installed

The pkg install lays down sibling skills that document the features in depth; they appear in future skill searches:

| Skill | Covers |
|---|---|
| `adom-desktop` (main) | the full verb reference + shell/process/file/window patterns, status+durationMs result shape |
| `adom-desktop-pup` | Puppeteer real-Chrome automation (browser_open_window/navigate/screenshot/eval, multi-session profiles) |
| `adom-desktop-kicad` | KiCad bridge (open schematics/boards, DRC, library install, 3D viewer, automation) |
| `adom-desktop-fusion` | Fusion 360 bridge (.f3d/.f3z, STEP/GLB/.lbr import-export, BOM/params, Fusion API) |
| `adom-desktop-direct-api` | the loopback HTTP API for sibling apps (Adom Hydrogen) |

But you don't need to read those to act: **`adom-desktop commands` is always the live source of truth** for what verbs exist right now. Bridges installed on the Mac ship their own skills; `adom-desktop sync_skills` pulls them.

## 6: Why this skill exists

Adom Bridge is its own repo with its own release cadence; the deep feature docs ship with the binary (so a binary release doesn't force a platform release). This skill is the stable, always-present entry point. Its one job is to get you to `adom-desktop commands`, the runtime catalog, instead of guessing.