Grok Bot

@@ -1,57 +1,249 @@ # grok-bridge -Two-way street between Grok Bot and Adom.+Claude, Codex, and Hydrogen talk to **Grok Bot** on your Windows or Mac. Grok Bot gets Adom Anywhere so they work as one. -- **Out:** Claude, Codex, and Adom Hydrogen talk to the Grok Bot app on your Windows or Mac so they work as one cohesive unit. `grok_*` can **open / close / resize / screenshot / record** the Grok Bot window, **report thinking vs idle** (`grok_chat_status`) and **read the visible transcript** (`grok_chat_read`), and **create bots / channels** via the Grok Bridge webhook.-- **Back:** Grok Bot gets Adom Anywhere (all of Adom's skills) so it knows how to use Adom.+Two-way street. Cloud AIs drive the **Grok Bot.exe** window. Grok Bot drives the rest of Adom — desktops, wiki, KiCad, Chrome — as a first-class Anywhere character. -Two products, one page (same shape as pup):+Wiki: [wiki.adom.inc/adom/grok-bridge](https://wiki.adom.inc/adom/grok-bridge) -1. **Runtime (release zip)** — a small Python stdlib HTTP server Adom Bridge spawns on the PC. Keyword **grok**. Talks TO Grok Bot the way kicad talks to KiCad: detect the host app (`Grok Bot.exe`), drive windows via `ab` `desktop_*` callbacks. There is no public Grok HTTP API. Never modifies ab-core. Cursor is last-resort fallback only if Grok Bot.exe is missing.-2. **Skills pkg** — teaches cloud AIs the `grok_*` verbs **and** installs Adom Anywhere on Grok Bot (Claude Desktop / Codex class). `install.sh` deploys `grok` + `grok-anywhere` into `~/.claude/skills`, `~/.codex/skills` if present, `~/.grok/skills`, and `/home/box/agent-data/workflows` if that parent exists.+![Grok Bot — Claude, Codex, and Hydrogen on one street](docs/hero.png) -Adom Bridge loads the runtime from the release zip. The skills package is what lands Anywhere on Grok Bot and `grok_*` on the other AIs.+*The Grok Bot window, sized like the product: bots in the sidebar, a live thread in the middle, the agent’s computer on the right.* -Wiki: https://wiki.adom.inc/adom/grok-bridge+--- -## Host app+## Talk to Grok Bot — every command type -**Grok Bot** — standalone Electron app, not Cursor.+This is the product. `grok_*` is how a cloud AI 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**. -- Windows: `%LocalAppData%\Programs\Grok Bot\Grok Bot.exe` (e.g. `C:\Users\john\AppData\Local\Programs\Grok Bot\Grok Bot.exe`)+Always pass `--ai-thread`. When more than one desktop is connected, pass `--target` (`AdomLapper`, `ConfRoomROG`). Windows open in the background. Nobody steals the keyboard.++![Grok Bot three-pane window: sidebar, grok-bridge thread, live screen](docs/screenshots/01-overview.png)++*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.++![Sidebar: grok-bridge, Bridge Test, John's channel, New bot](docs/screenshots/02-sidebar-bots.png)++*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.++![Center pane: grok-bridge thread with composer](docs/screenshots/03-chat-thread.png)++*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. 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).++![Routines list: Grok Bridge webhook, When a webhook fires](docs/screenshots/05-webhook-routine.png)++*Right-pane Routines. One chip: **Grok Bridge webhook** / When a webhook fires. No URL. No key.*++![Routine editor: Name Grok Bridge webhook, Active, Instruction, When a webhook fires](docs/screenshots/06-webhook-editor.png)++*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.++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.++![Right pane: grok-bridge's screen, Chrome and terminal on the box](docs/screenshots/04-computer-feed.png)++*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`+- Window title `Grok Bot` · process `Grok Bot.exe` - macOS: `/Applications/Grok Bot.app` - Linux: `grok-bot` / `Grok Bot` on PATH -`grok_open` offers to launch it; it does not tell the user to download the host app.+`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. -## Verbs+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. -`grok_readiness` · `grok_prewarm` · `grok_describe` · `grok_status` · `grok_open` · `grok_screenshot` · `grok_list_windows` · `grok_chat_status` · `grok_chat_read` · `grok_send` · `grok_uninstall` · `grok_close` · `grok_resize` · `grok_record_start` · `grok_record_stop` · `grok_record_status` · `grok_login` · `grok_logout` · `grok_plugin_install` · `grok_webhook_status` · `grok_webhook_bind` · `grok_webhook_ensure` · `grok_webhook_fire` · `grok_bot_create` · `grok_channel_create` · `grok_bot_list`+![Plugins and John Lauer at the bottom of the sidebar](docs/screenshots/07-account-plugins.png) -CLI: `adom-bridge grok_*`. Always `--ai-thread`. Background by default.+*Plugins and the signed-in account. `grok_plugin_install {id}` lands here. Login and logout never type a password.* -`grok_send {message}` toasts `Grok Bot: {message}` and appends `~/.adom/grok-inbox.jsonl`. Desktop typing is opt-in — don't steal the keyboard.+--- -`grok_chat_status` reports `thinking` vs `idle` from the UIA working chip (`"<agent> is working"`). `grok_chat_read` reads the visible Document transcript (`desktop_ui_text` role Document range all). Optional `limit` truncates from the end. Never OCR-first, never CDP 9222, never webhook keys in the payload.+## Adom Anywhere — skills on Grok Bot -## Webhook+The other direction. This Grok Bot session is Claude-Desktop-class: an Anywhere character with `adom-bridge` on PATH. -Prefer `grok_webhook_ensure {}` — it reads UIA Edit controls **Webhook URL** / **Webhook key** from the Grok Bot routine pane (no OCR) and writes `~/.adom/grok-webhook.json` (Windows: `%USERPROFILE%\.adom\grok-webhook.json`) as `{url, key, header, boundAt}`. Manual `grok_webhook_bind {url, key}` still works. The key is never logged or returned. POSTs use `Authorization: Bearer`. Then `grok_bot_create` / `grok_channel_create` / `grok_bot_list`.+```bash+adom-wiki pkg install adom/grok-bridge+``` -## Runtime zip (what ab spawns)+That drops **grok** + **grok-anywhere** into `~/.claude/skills`, `~/.codex/skills` if present, `~/.grok/skills`, and `/home/box/agent-data/workflows` if that parent exists. Grok Bot then knows Adom the same way Claude and Codex do. -Zip root (no top directory): `server.py`, `bridge.json`, `BRIDGE_VERSION`, `grok_detect.py`, `caller_identity.py`, `handlers/*.py`.+From this session, always: -`spawn.kind` = python, `port` 0, `healthEndpoint` `/status`, `persistent` true, `killImageName` python.exe. Binds `ADOM_BIND_HOST` (default `127.0.0.1`) only.+```bash+adom-bridge --ai-thread "Grok Bot" --target NAME <verb> '<json>'+``` -## Skills vs runtime+`--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.++![Sidebar bots and channels after Anywhere is installed](docs/screenshots/02-sidebar-bots.png)++*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+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](https://wiki.adom.inc). After that, this computer is a wiki client — not a screenshot of one.++![The box desktop this bootstrap runs on](docs/screenshots/04-computer-feed.png)++*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](https://wiki.adom.inc/adom/adom-bridge/issues/101).++![Account row: John Lauer](docs/screenshots/07-account-plugins.png)++*The signed-in Grok Bot account. Wiki auth on this computer is CLI `whoami`, not a secret pasted into chat.*++---++## Run KiCad for the user from this CLI++Grok Bot is the operator. Drive the user’s KiCad through Adom Bridge — footprint editor, PCB, the board on the desk — with the same `--ai-thread` / `--target` rules as everything else.++```bash+adom-bridge --ai-thread "Grok Bot" --target AdomLapper kicad_*+```++Prefer `kicad_*` over Shell. The activity log, approval toasts, and attribution only stay intact on the ab path. The **New bot** snippet in the sidebar (“KiCad Footprint Editor on R…”) is that loop already running.++![New bot snippet: KiCad Footprint Editor](docs/screenshots/02-sidebar-bots.png)++*New bot, last line KiCad Footprint Editor. Grok Bot drove that from this CLI, on AdomLapper, as itself.*++---++## 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"}`. |++![Full Grok Bot window — every surface the verbs touch](docs/screenshots/01-overview.png)++*One window, twenty-six verbs. Sidebar, thread, box feed, webhook chip.*++---++## Install++Skills (this page):++```bash+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` | ab `bridges-cache` on the PC |-| Contains | `SKILL.md`, `skills/grok-anywhere`, install.sh | Python HTTP server |-| Does not contain | `server.py` / the zip | SKILL.md |+| Lands | container `~/.claude/skills/grok` (and Codex / Grok / box workflows) | ab `bridges-cache` on the PC |+| Contains | `SKILL.md`, `skills/grok-anywhere`, `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.++![Hero — two-way street, install both halves](docs/hero.png) -Repo name `grok-bridge` ≠ skill name `grok`.+*Install the skills pack so cloud AIs know `grok_*` and Grok Bot knows Adom. The runtime zip is what the desktop actually spawns.*