grok-bridge

Grok Bridge lets Adom talk to Grok Bot.

That is the product. grok_* is how Adom reaches the Grok Bot app on Windows or Mac. There is no public Grok HTTP API. The runtime on the desktop talks to Grok Bot.exe and a bound webhook routine named Grok Bridge webhook.

Adom users are predominantly electrical engineers. Providers leapfrog each other — Claude, Codex, Grok, Gemini, whoever is ahead this week. Adom's environment is built so you always get the one that's winning, without leaving the power tools you already use. Adom Bridge is how any desktop-oriented environment becomes an AI-first surface Adom already knows how to talk to.

Wiki: wiki.adom.inc/adom/grok-bridge

The Grok Bot window. Grok Bridge is how Adom reaches it. Adom Bridge is how the rest of the desktop becomes something Adom can talk to.

---

Talk to Grok Bot — every command type

This is the product. grok_* is how Adom reaches the Grok Bot app on the PC. There is no public Grok HTTP API. The runtime on the desktop talks to Grok Bot.exe and a bound webhook routine named Grok Bridge webhook.

Always pass --ai-thread. When more than one desktop is connected, pass --target (AdomLapper, ConfRoomROG). Windows open in the background. Nobody steals the keyboard.

The current Grok Bot window. Left: bots and channels. Center: this grok-bridge thread. Right: the agent’s Linux box plus the Grok Bridge webhook routine.

Create bots

grok_bot_create {name, description?}. Fires webhook event create_bot. Bridge Test was created this way — it shows up in the sidebar like any other agent.

Search, then the bot list. grok-bridge is selected. Bridge Test is a webhook-created bot. John’s channel and New bot sit underneath. Plugins and John Lauer at the bottom.

Create channels

grok_channel_create {name, member_ids}. Fires create_channel. The channel lands in the same sidebar — John's new chan… is the shape of that.

List bots

grok_bot_list. Fires list_bots. The cloud agent lists agents; you see them in the sidebar the next time you look.

Read a thread

grok_chat_status reports thinking vs idle from the working chip ("<agent> is working"). grok_chat_read returns the visible transcript. Optional limit truncates from the end (latest). Never OCR-first. Webhook keys never come back in the payload.

The grok-bridge thread. Status and transcript verbs read this pane — thinking chip, visible messages, composer at the bottom.

Send into a thread

grok_send {message} toasts Grok Bot: {message} and appends ~/.adom/grok-inbox.jsonl. Typing into the composer is opt-in. Default path does not steal the keyboard.

Webhook events that wake Grok Bot

A routine already named Grok Bridge webhook sits in the right pane, trigger When a webhook fires. Prefer grok_webhook_ensure {} — it reads the UIA Edit controls Webhook URL and Webhook key from that pane (no OCR, no human copy-paste) and writes %USERPROFILE%\.adom\grok-webhook.json on the PC. The key is never logged, never returned, never put in chat or this wiki.

grok_webhook_fire with event: ping is the smoke test. Optional agent (teammate name or id) tells grok-bridge to relay into that bot's thread and paste the reply back here — there is still one mailbox (this routine). HTTP 200 is only a runUuid; poll grok_chat_read for a nonce in payload.

Bound events:

Event	What Grok Bot does
ping	Reply that grok-bridge reached you (include desktop / target name)
create_bot	Create an agent (name, optional description)
create_channel	Create a channel (name, optional member_ids)
list_bots	List agents
notify	Surface a notification
plugin_install	Open plugin install for {id}
login_needed	Ask the human to sign in
logout_done	Confirm sign-out

Manual fallback: grok_webhook_bind {url, key} still works. Check bind with grok_webhook_status (hostname only — never the key).

Right-pane Routines. One chip: Grok Bridge webhook / When a webhook fires. No URL. No key.

The routine editor. Name, Active, Instruction, trigger When a webhook fires. Secrets were not expanded.

---

The agent's computer / video feed

The right-pane preview titled grok-bridge's screen is this Grok Bot agent’s Linux box desktop — Chrome, terminal, the dock. It is the live feed humans see while the thread runs.

The box is a real computer: 16 GB RAM, 8 CPUs, 16 GB swap. Measured on this grok-bridge session (MemTotal 16397684 kB, nproc 8). That is enough to run KiCad here while the thread runs — an EE can offload board work onto this computer, not only their laptop.

grok-bridge on the PC can screenshot and record the Grok Bot.exe window (grok_screenshot, grok_record_start {reason} — reason is required). That is the host app on Windows or Mac, not the box.

Honest: there is no grok_box_screenshot verb yet. The pane is the feed. If the pane is open, a window screenshot of Grok Bot includes it.

grok-bridge's screen — live box desktop. Chrome, a tool icon, a terminal. This is the agent’s computer, not AdomLapper.

---

Control the Grok Bot app

Host app is Grok Bot.exe (standalone Electron), not Cursor.

• Windows: %LocalAppData%\Programs\Grok Bot\Grok Bot.exe
• User data: %APPDATA%\Grok Bot
• Window title Grok Bot · process Grok Bot.exe
• macOS: /Applications/Grok Bot.app
• Linux: grok-bot / Grok Bot on PATH

grok_open launches it in the background. grok_close hides the window (prefer hide over kill). grok_resize sets bounds in physical pixels. grok_screenshot captures the Grok Bot window. grok_record_start / grok_record_stop / grok_record_status wrap window recording — reason is required to start.

grok_login / grok_logout never type passwords. Login opens settings; the human clicks Sign In with Cursor. Logout tries Sign Out, else needsHuman. grok_plugin_install {id} opens the plugin add flow — the app UI confirms.

Cursor is last-resort fallback only if Grok Bot.exe is missing (hostAppFallback: "Cursor"). Never kill Cursor. grok_open offers to launch; it does not send anyone to a download page.

Plugins and the signed-in account. grok_plugin_install {id} lands here. Login and logout never type a password.

---

Adom Anywhere — skills on Grok Bot

The other direction — secondary. Grok Bot becomes an Anywhere character so the same electrical engineer can drive KiCad, the wiki, and desktops from Grok Bot, with adom-bridge on PATH.

adom-wiki pkg install adom/grok-bridge

That drops the USER pack into ~/.claude/skills, ~/.codex/skills if present, ~/.grok/skills, and /home/box/agent-data/workflows if that parent exists: grok (core), grok-anywhere, grok-app-control, grok-chat, grok-record, grok-webhook, grok-account. DEV/PUBLISH (grok-dev, grok-publish) stay in the wiki repo under dev-skills/ and are not in the pkg. Skills land where each provider looks; the point is the same EE can work from Grok Bot without leaving Adom.

From this session, always:

adom-bridge --ai-thread "Grok Bot" --target NAME <verb> '<json>'

--target when more than one desktop is connected. Prefer ab verbs over Grok ListMachines / Shell so the activity log stays intact. ConfRoomROG is ab-only.

Same sidebar, now with Anywhere behind it. This session can ping a desktop, install a wiki app, or drive KiCad — as Grok Bot, not as a borrowed Claude.

---

adom/core on this computer

Bootstrap the box so it has Adom awareness:

bash <(curl -fsSL https://wiki.adom.inc/static/bootstrap.sh) adom/core

That puts adom-wiki and adom-bridge on PATH, installs core skills, and points at the wiki host wiki.adom.inc. After that, this computer is a wiki client — not a screenshot of one.

The same Linux box. Chrome and a terminal on the dock — where adom/core lands, and where wiki CLI auth happens.

---

Session / wiki auth

Once this Grok Bot computer is authed (adom-wiki whoami as the user), it talks to the wiki natively: adom-wiki pkg install any app, repo clone / repo push, download release zips, run them. Chip fetcher and other wiki apps run as skills. pup_* opens real Chrome on the user’s PC (durable adom-you profile, logins stay).

There is no “paste me a token” verb. Do not invent one. The live path is wiki CLI auth on the box + skills install.

The intended path is not borrowing a human token. grok-bridge lives inside Adom Bridge, so ab can mint a Grok Bot-scoped session token — the same injection shape as ADOM_DIRECT_API_URL + ADOM_BRIDGE_TOKEN — tracked as Grok Bot. That mint API does not exist yet. Track it: Mint a unique session token for grok-bridge, tracked as Grok Bot.

The signed-in Grok Bot account. Wiki auth on this computer is CLI whoami, not a secret pasted into chat.

---

Offload KiCad onto this computer

An electrical engineer keeps the laptop for thinking. Grok Bot runs KiCad 10 here — 16 GB RAM, 8 CPUs — so the board work does not sit on AdomLapper.

This session already did it. Arduino Uno is open in pcbnew on grok-bridge's desktop (you can see it on grok-bridge's screen). 36 pads, 28 nets, the Uno outline, headers J1–J4.

dbus-run-session -- env DISPLAY=${DISPLAY:-:3} \
  pcbnew /home/box/kicad-offload/Arduino_Uno/Arduino_Uno.kicad_pcb

pcbnew is KiCad 10 via flatpak on this computer (org.kicad.KiCad). The session bus is required; without it the editor does not come up. Project files live at /home/box/kicad-offload/Arduino_Uno.

Leave it running. The live feed is the proof the offload landed.

Arduino Uno — PCB Editor, on this computer, not AdomLapper. Board outline, mounting holes, power/analog/digital headers, ICSP. Driven from this grok-bridge session.

---

Verb catalog

CLI: adom-bridge --ai-thread "<thread>" [--target NAME] grok_<verb> '<json>'. Twenty-six verbs. Background by default.

Verb	What it does
grok_readiness	Layered host-app probe. Zero side effects.
grok_prewarm	Re-detect. {wait:true} just re-detects.
grok_describe	Catalog with hint / related / pitfalls.
grok_status	Detect + last send + inbox + webhook bound.
grok_open	Launch Grok Bot in the background.
grok_list_windows	Find the Grok Bot window (not Chrome ai-grok-bot).
grok_screenshot	Screenshot the Grok Bot.exe window.
grok_close	Hide the window. Never kill Cursor.
grok_resize	Set window bounds (physical px).
grok_record_start	Record the Grok Bot window. reason required.
grok_record_stop	Stop recording.
grok_record_status	Recording status.
grok_chat_status	Thinking vs idle.
grok_chat_read	Visible transcript. Optional limit from the end.
grok_send	Toast + durable inbox. Typing is opt-in.
grok_login	Open settings. Does not type passwords.
grok_logout	Sign Out via UI, else needsHuman.
grok_plugin_install	{id} required. App UI confirms.
grok_webhook_status	Bound? Returns urlHost only.
grok_webhook_ensure	Scrape routine pane, write json on the PC.
grok_webhook_bind	Manual {url, key}. https required.
grok_webhook_fire	POST {event, payload}. Try ping.
grok_bot_create	{name, description?}. Event create_bot.
grok_channel_create	{name, member_ids?}. Event create_channel.
grok_bot_list	Event list_bots.
grok_uninstall	Tells you to bridge_uninstall {"name":"grok"}.

One window, twenty-six verbs. Sidebar, thread, box feed, webhook chip.

---

Skills in this pack

This page ships a library, not one file (Bridge SDK: core USER skill + sub-skills by area; DEV/PUBLISH stay in the repo).

Skill	Kind	What it teaches
grok	USER (pkg)	Cold-start, identity, which verb family to pick
grok-anywhere	USER (pkg)	Grok Bot as an Adom Anywhere character (drives the PC)
grok-app-control	USER (pkg)	Open / close / resize / screenshot / list windows
grok-chat	USER (pkg)	Thinking vs idle, visible transcript, toast + inbox
grok-record	USER (pkg)	Record the Grok Bot.exe window
grok-webhook	USER (pkg)	Bind Grok Bridge webhook, fire events, bots/channels
grok-account	USER (pkg)	Login / logout / plugin install (no passwords)
grok-dev	DEV (repo)	Architecture, hwnd unwrap, hints-in-output
grok-publish	PUBLISH (repo)	Zip vs pkg, files[] allowlist, .gitignore trap

adom-wiki pkg install adom/grok-bridge installs SKILLS, not the runtime zip.

---

Install

Skills (this page):

adom-wiki pkg install adom/grok-bridge

Runtime (what Adom Bridge spawns on the PC): release zip, via bridge_install / refresh_bridges. Skills ≠ runtime. Repo name grok-bridge ≠ skill name grok.

Always --ai-thread. --target when more than one desktop is connected (AdomLapper, ConfRoomROG).

	Skills pkg (adom-wiki pkg)	Release zip
Lands	container ~/.claude/skills/grok (and Codex / Grok / box workflows)	ab bridges-cache on the PC
Contains	SKILL.md + 6 user sub-skills, install.sh	Python HTTP server (server.py, handlers/, bridge.json)
Does not contain	server.py / the zip	SKILL.md

spawn.kind = python, port 0, healthEndpoint /status, persistent true. Binds loopback only.

Install the skills pack so Adom can talk to Grok Bot. The runtime zip is what the desktop actually spawns.