Skip to content
Back to search

gbot-marketplace

Message Grok Bot from Codex, Claude Code, and Cursor. Codex/Claude tools use local sockets on the user's registered machines only (no remote transport); from the Grok Bot box, run gbot via Grok Bot Shell with a machineId.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ScriptedAlchemy/grok-bot-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ScriptedAlchemy/grok-bot-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/scriptedalchemy--grok-bot-cli/badge.svg)](/listings/scriptedalchemy--grok-bot-cli)

HTML

<a href="/listings/scriptedalchemy--grok-bot-cli"><img src="/api/listings/scriptedalchemy--grok-bot-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install --global grok-bot-cli

Requires Node.js 22.19.0+ and the Grok Bot desktop app on macOS, Linux, or Windows. Open Grok Bot and sign in once; `gbot` automatically uses the app's encrypted session and routing credentials. No token copying is required. If the app removes its cached gateway route while the cloud computer sleeps, the CLI uses the active account in `sand-secrets.json` to request a fresh route through `EnsureSandBox`. Signed-out and inactive saved accounts are never selected. Backend requests use the installed Grok Bot app version, read from the app's `desktop-status.json` (or the macOS app bundle); `SAND_CLIENT_VERSION` remains an explicit override. On Linux the app keeps its session under `~/.config/Grok Bot` (or `$XDG_CONFIG_HOME`); when it is stored in the system keyring, `gbot` reads the key with `secret-tool` (package `libsecret-tools`). On Windows the session lives under `%APPDATA%\\Grok Bot` and decrypts with the app's DPAPI-wrapped Safe Storage key.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 1 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {"description":"Message Grok Bot from Codex, Claude Code, and Cursor. Codex/Claude tools use local sockets on the user's registered machines only (no remote transport); from the Grok Bot box, run gbot via Grok Bot Shell with a machineId.","name":"gbot-marketplace","owner":{"name":"gbot"},"plugins":[{"author":{"name":"Zack Jackson","url":"https://github.com/ScriptedAlchemy"},"description":"Message Grok Bot from Codex, Claude Code, and Cursor. Codex/Claude tools use local sockets on the user's registered machines only (no remote transport); from the Grok Bot box, run gbot via Grok Bot Shell with a machineId.","homepage":"https://github.com/ScriptedAlchemy/grok-bot-cli#readme","keywords":["grok","grok-bot","grokbot","gbot","cursor","ai-agents","automation","terminal","cli","agent-bundle"],"license":"MIT","name":"gbot","repository":"https://github.com/ScriptedAlchemy/grok-bot-cli","source":"./artifact","version":"0.12.5"}]}
README.md · README · 400 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # grok-bot-cli
  2. [![npm version](https://img.shields.io/npm/v/grok-bot-cli.svg)](https://www.npmjs.com/package/grok-bot-cli)
  3. Manage [Grok Bot](https://cursor.com/help/grok-bot/plans) agents, groups, and messages from your terminal.
  4. ![Live create, group, send, and delete smoke test](https://raw.githubusercontent.com/ScriptedAlchemy/grok-bot-cli/main/demo/grok-bot-cli-demo.gif)
  5. [Watch the MP4](https://github.com/ScriptedAlchemy/grok-bot-cli/blob/main/demo/grok-bot-cli-demo.mp4)
  6. ## Install
  7. ```sh
  8. npm install --global grok-bot-cli
  9. ```
  10. Requires Node.js 22.19.0+ and the Grok Bot desktop app on macOS, Linux, or Windows. Open Grok Bot and sign in once; `gbot` automatically uses the app's encrypted session and routing credentials. No token copying is required. If the app removes its cached gateway route while the cloud computer sleeps, the CLI uses the active account in `sand-secrets.json` to request a fresh route through `EnsureSandBox`. Signed-out and inactive saved accounts are never selected. Backend requests use the installed Grok Bot app version, read from the app's `desktop-status.json` (or the macOS app bundle); `SAND_CLIENT_VERSION` remains an explicit override. On Linux the app keeps its session under `~/.config/Grok Bot` (or `$XDG_CONFIG_HOME`); when it is stored in the system keyring, `gbot` reads the key with `secret-tool` (package `libsecret-tools`). On Windows the session lives under `%APPDATA%\\Grok Bot` and decrypts with the app's DPAPI-wrapped Safe Storage key.
  11. ## Use
  12. ```sh
  13. gbot bots list
  14. gbot bots create --name Researcher
  15. gbot bots update Researcher --description "Research the launch" --notify on
  16. gbot bots create --name Writer
  17. gbot groups create --name Launch --member Researcher --member Writer --description "Ship together"
  18. gbot groups update Launch --title "Launch room" --hidden off
  19. gbot send Researcher "Summarize the launch status."
  20. gbot send Launch "Share your updates."
  21. gbot thread Researcher
  22. gbot thread Researcher --after <last-entry-id> --json
  23. gbot skills list
  24. gbot skills add ./skills/poteto-mode
  25. gbot skills remove poteto-mode
  26. gbot groups delete Launch
  27. gbot bots delete Researcher
  28. gbot bots delete Writer
  29. ```
  30. `update` fields: `--name` `--description` `--title` `--avatar-shape` `--avatar-color` `--notify on|off` `--hidden on|off`. `--description` is the UI Instructions field.
  31. `gbot skills` manages the skill library over the gateway. Grok Bot keeps one
  32. library per account; every bot reads the same list, and there is no per-bot
  33. attach. `add` posts a `SKILL.md` (or a directory holding one) and every bot sees
  34. it. `list` shows each entry's `source`: `workflow` is your library, `managed` is
  35. team-published, `plugin` comes from a marketplace install, `automation` is a
  36. scheduled routine. `remove` deletes a `workflow` skill by id or exact name, for
  37. every bot, and refuses the other sources. Adding the same file twice yields two
  38. same-named skills; remove by id then. There is no `--files` mode for skills.
  39. `gbot thread --after ID` filters the bounded tail locally and returns entries strictly
  40. after that opaque entry ID. Its JSON includes `cursor`, `entryCount`, and `gapReset`.
  41. An unchanged poll has `entryCount: 0`; an unknown or expired ID returns one bounded
  42. snapshot with `gapReset: true`. The gateway request remains limit-only.
  43. Run `gbot --help` for every command.
  44. Options are command-local (for example, `gbot send --history-dir DIR ...`);
  45. `--json` prints the canonical JSON result; `send` and the `codex` commands also report failures as
  46. a JSON document on stdout with `exitCode` (see below), every other command
  47. prints the failure message on stderr and exits 1.
  48. ## Messaging a live Claude Code session
  49. Claude Code has a native [Channels API](https://code.claude.com/docs/en/channels-reference),
  50. so this integration needs no desktop shim. The Claude plugin includes an opt-in
  51. `claude-channel` MCP server; Codex and Grok callers can use `claude_send`, or the
  52. local CLI, to send a message and receive Claude's explicit reply.
  53. Claude channels live on the **user's registered machine** (the same host that runs
  54. Claude Code), not on the Grok Bot agent box (`HOME=/home/box`). gbot has no remote
  55. transport: from the box, use Grok Bot Shell with a machineId to run
  56. `gbot claude send` on that computer. Auth stays with that machine's native Claude login.
  57. After installing this version of the Claude plugin, launch a named session:
  58. ```sh
  59. GROK_BOT_CLAUDE_CHANNEL=review claude --dangerously-load-development-channels plugin:gbot@gbot-marketplace
  60. # From another terminal on the same machine and user account:
  61. gbot claude send review "Reply with GBOT_CLAUDE_OK" --json
  62. ```
  63. Accept Claude's development-channel prompt. Custom channels are a research preview
  64. and require session opt-in and any applicable organization policy. Claude must be
  65. signed in. The development flag permits this channel; it does not bypass tool
  66. approvals. `claude_send` takes `name`, `message`, and optional `timeoutMs` (default
  67. 60000, maximum 120000). Claude uses `claude_reply` with the incoming `request_id`.
  68. Only that explicit reply completes the call; a notification alone is not proof
  69. Claude received or processed the message. Timeout/disconnect returns `unknown`;
  70. do not automatically resend.
  71. Each name selects one live session. Sockets live under `~/.grok-bot-cli/claude/`
  72. in a user-owned 0700 directory, with mode 0600 sockets. Access grants messaging
  73. to local processes running as the same user. No TCP listener, automatic permission
  74. approval, conversation-history scraping, or background daemon is installed.
  75. Without `GROK_BOT_CLAUDE_CHANNEL`, the channel is disabled. Shut down the owning
  76. Claude session to close it. A crashed process may leave a socket: confirm the
  77. named session is stopped before removing that socket and restarting. A second
  78. session with the same name fails rather than taking over the first.
  79. This targets opted-in Claude Code sessions, not arbitrary existing sessions or
  80. ordinary Claude Desktop chats. Remote Grok runtimes need local tool execution to
  81. reach the socket; installing an MCP artifact does not establish that connection.
  82. Claude can use the existing `gbot_send`/`gbot_thread` and `codex_send` tools for
  83. outgoing messages; its own tool permissions still apply.
  84. ## Automatic Grok ↔ Codex replies
  85. In a native Codex invocation, `gbot_send` sends once and returns a durable exchange
  86. receipt. Continue working: matching Grok replies arrive in the originating Codex
  87. thread automatically. That thread's next answer is not sent back to Grok unless
  88. you deliberately send again. The background worker survives the MCP caller exiting. Outgoing MCP tool calls
  89. still follow the host's tool-approval policy; the bridge does not change it.
  90. When native identity is unavailable (including Cursor), supply `codexThreadId` on
  91. the send, or make a one-time `gbot_bridge_start` binding with `grokTarget`,
  92. `codexThreadId` and optional `expectedCwd`. New visible Grok bot messages then arrive
  93. in that Codex thread, and its corresponding terminal answer returns to Grok.
  94. Existing transcript history is not replayed. `codex_send` can also request a return
  95. with `replyToGrok` or `bindingId`. Managed delivery defaults to guarded steering of
  96. active work; `busyPolicy: "reject"` on a binding refuses busy threads. A managed
  97. `codex_send` can select `whenBusy` for that one delivery; omitting it uses the
  98. binding's stored policy. An override does not change subsequent linked traffic.
  99. **Rejections and failed turns are explained.** A managed receipt that is `rejected` carries `reason` plus `detail` (the daemon's own error text) and the CLI/MCP result adds the next step; a failed Codex turn is returned to Grok as `Codex turn failed with no final text: <Codex error>`. `--when-busy queue` is not available with `--reply-to-grok`/`bindingId` (the experimental queue cannot carry the Grok return route): omit `--when-busy` (an active turn is steered, an idle thread starts a turn), or pass `steer` / `reject`.
  100. Without an identifiable native source or explicit route, `gbot_send` preserves the
  101. ordinary send and returns `replyRoute: {mode: "manual", reason: "source-unavailable"}`;
  102. read with `gbot_thread` later. `replyMode: "manual"` deliberately selects that flow.
  103. An automatic-route startup failure never falls back to an untracked send.
  104. ```sh
  105. # CLI sends remain manual unless routing is explicitly requested.
  106. gbot send --reply-mode auto --codex-thread-id THREAD_ID Researcher "Please investigate"
  107. gbot codex bridge start --codex-thread-id THREAD_ID --expected-cwd /project Researcher --json
  108. gbot codex bridge status --json
  109. gbot codex send --reply-to-grok Researcher THREAD_ID "Investigate and return your final answer"
  110. gbot codex bridge stop --binding-id BINDING_ID --json
  111. # Explicitly stop the process; pending records remain for a later restart.
  112. gbot codex bridge stop --worker --json
  113. ```
  114. `gbot_bridge_status` separates worker health, binding coverage, submission, execution,
  115. return delivery and pending operator interactions. `unknown` is not rejection: inspect
  116. status before resending. Caller-supplied `requestId` (CLI `--request-id`) permits exact
  117. replay of a tracked send without another submission; returned `controlRequestId` is
  118. that control identity, separate from the gateway's transcript `requestId`.
  119. Explicit chain `hop`/`correlationId` remain bounded. Automatic CLI routes own their
  120. envelope; omit the legacy `--envelope` and `--reply-to` flags. Managed Codex return
  121. routes also reject explicit `expectedTurnId`/`--expected-turn-id`; use plain Codex
  122. send when a caller-selected turn guard is required. If a binding and an explicit
  123. Grok target are supplied together, the target must resolve to that binding's recipient.
  124. Paused gaps/capacity or unsupported interactions need attention; never guess a cursor
  125. or automatically approve. `gbot_codex_respond` / `gbot codex bridge respond` requires
  126. current `interactionId`, `generation`, `threadId`, `turnId` and binding/exchange scope.
  127. Supply one-time `decision: accept|decline|cancel`, or `answersJson` containing exact
  128. question IDs mapped to `{"answers":["answer"]}`. Session permissions and policy
  129. amendments remain in the owning Codex UI.
  130. State lives in the user-owned `~/.grok-bot-cli/relay/` directory, or
  131. `GROK_BOT_RELAY_DIR`, outside plugin caches. Profile mismatches fail visibly; gateway
  132. overrides and thread restrictions cannot reuse a differently authorized worker.
  133. Authentication failures use bounded retries (1..30 seconds) from the saved cursor;
  134. restored credentials do not reset coverage or resend uncertain submissions.
  135. No login service is installed. Network reconnects are automatic; a dead process
  136. needs a new tracked send or bridge start to resume saved routes. A dead worker is
  137. reported as stopped, not running.
  138. `gbot codex bridge run --lifetime-ms 60000` runs in the foreground for an explicit
  139. bounded lifetime (default and maximum 23 hours), then closes cleanly before the CLI
  140. renderer deadline. For an unlimited foreground service entry, run
  141. `node /path/to/plugin/scripts/gbot-relay.mjs` (npm package: `dist/scripts/gbot-relay.mjs`)
  142. with the same authorized environment. SIGINT/SIGTERM or explicit worker stop closes
  143. observation without interrupting a Codex turn. Windows retains the Codex Unix-socket
  144. limitation.
  145. Codex, Cursor, Claude and portable artifacts contain these tools and the worker.
  146. Grok Bot participates through its existing gateway conversation; a native Grok plugin
  147. loader or remote stdio tunnel has not been established. Artifact availability alone
  148. does not mean a host has loaded the plugin.
  149. ## Gateway URL policy
  150. By default `gbot` only sends credentials to expected hosts:
  151. - **Gateway** URLs (box + API): `https` on `*.cursor.sh` / `*.cursor.com` / `*.cursorvm.com` (the box family EnsureSandBox returns).
  152. - **Backend** URLs (`EnsureSandBox` / `CURSOR_API_BASE_URL`): `https` on `*.cursor.sh` / `*.cursor.com` only — never `*.cursorvm.com`, so a Cursor access token cannot be pointed at a box host.
  153. - `GROK_BOT_ALLOW_LOCAL_GATEWAY=1` — permit `http(s)://127.0.0.1`, `localhost`, and `::1` for **gateways** only (local/dev). Prints a one-shot stderr warning.
  154. - `GROK_BOT_ALLOW_ANY_GATEWAY=1` — disable host checks (unsafe; for break-glass only). Prints a one-shot stderr warning.
  155. All gateway / `EnsureSandBox` fetches use `redirect: "error"` so credentials are not followed across redirects.
  156. ## Messaging Codex threads from Grok Bot
  157. `gbot codex` attaches to a local [Codex app-server](https://learn.chatgpt.com/docs/app-server) daemon and injects messages into its threads with the documented JSON-RPC methods (`initialize`, `thread/list`, `thread/resume`, `turn/start`).
  158. ```sh
  159. codex app-server daemon start # once per machine session
  160. gbot codex status # socket, daemon version, reachability
  161. gbot codex list-threads --limit 10 # newest activity first: id, status, cwd, updated, preview
  162. gbot codex list-threads --query zerofs --active-within 7d # find an old-but-active thread
  163. gbot codex send <threadId> "Grok here: the build is green, please continue."
  164. gbot codex send --model gpt-6-astra --effort high <threadId> "Review this change"
  165. gbot codex new --cwd /path/to/project --model gpt-6-astra --effort high "Start here"
  166. gbot codex wait <threadId> <turnId> --timeout-ms 1800000
  167. ```
  168. `send` resumes the thread, starts a turn with your text, prints the turn id, and returns; Codex keeps working after `gbot` disconnects. Every command accepts `--json`.
  169. `send` and MCP `codex_send` accept optional `model` and `effort` overrides (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`). `gbot codex new` and MCP `codex_new` use `thread/start` to create a thread with a required cwd and optional model, effort, and first message. Use `--expected-cwd` to guard the selected directory. `wait` accepts a caller timeout up to two hours and reconciles turn history after notification floods.
  170. **Which Codex you reach.** `gbot` connects to `$CODEX_HOME/app-server-control/app-server-control.sock` (default `~/.codex/...`) or the existing local socket set by `CODEX_APP_SERVER_SOCK`, with a built-in WebSocket client. The daemon must be started by `codex app-server daemon start`. `list-threads` shows the threads recorded under `CODEX_HOME` (CLI, TUI, VS Code); `send` uses the resumed thread state and selected busy policy: ordinary sends reject active work, while explicitly selected guarded steering can deliver into the active turn. Method and parameter names are pinned to the Codex release recorded in `src/core/codex-bridge.js` (`codex app-server generate-json-schema`); `status` prints the daemon and CLI versions so a stale daemon is visible, and `codex app-server daemon restart` picks up the installed CLI. Native Windows is not supported yet (AF_UNIX control socket); use WSL, Linux, or macOS.
  171. **User machines, not the Grok Bot box.** Codex must run on the same machine as gbot. Codex (and Claude) sessions live on the user's registered computers — for example their Linux desktop or Mac — not on the Grok Bot agent's sandbox VM (`HOME=/home/box`, no Codex install). gbot has **no remote transport**; it only dials a local Unix socket. When this process is on the box, do not call the Codex/Claude MCP tools there — run the `gbot` CLI on the user's machine through **Grok Bot Shell with a machineId**. On that machine, start the daemon with `codex app-server daemon start` (or bootstrap). Auth stays with each machine's native login; gbot does not store or export credentials.
  172. **ChatGPT Desktop limitation.** Desktop runs its own private stdio app-server and does not publish the shared control socket, so external clients cannot reach live Desktop tasks. When the socket is absent, `gbot codex status` exits 1 and says so, naming the upstream issues: [openai/codex#41014](https://github.com/openai/codex/issues/41014) and [openai/codex#41112](https://github.com/openai/codex/issues/41112). `gbot` never reads Desktop's temporary `CODEX_APP_TOOLS_PIPE_PATH` sockets under `/tmp/codex-browser-use/`; that channel is private to Desktop.
  173. **Pointing Desktop at the managed daemon (macOS).** Desktop injects `codex_app` overrides, so `CODEX_APP_SERVER_USE_LOCAL_DAEMON=1` alone cannot select the managed daemon. The workaround is a `CODEX_CLI_PATH` wrapper that rewrites Desktop's `codex … app-server` spawn into a stdio↔WebSocket bridge onto the managed control socket — no Desktop binary patches, no pipe scraping, no protocol change (`gbot` already speaks that socket). Do not use stock `codex app-server proxy` here: it hangs for Desktop stdio, so the shim ships its own bridge.
  174. ```sh
  175. gbot codex desktop-shim install # wrapper + bridge into ~/.codex/bin, LaunchAgent persists GUI env across logins
  176. gbot codex desktop-shim status # installed? CODEX_CLI_PATH pointing at it? daemon socket present?
  177. gbot codex desktop-shim uninstall # removes wrapper/bridge/LaunchAgent; Desktop falls back to stock Codex
  178. ```
  179. Install copies the scripts out of the package into durable `~/.codex/bin/` paths, so uninstalling the npm package never leaves Desktop pointing into a deleted checkout. The wrapper exports install-time `CODEX_HOME` and derives the socket from it at runtime (`CODEX_APP_SERVER_SOCK`), so custom `CODEX_HOME` layouts work; `gbot` itself resolves the socket the same way (`CODEX_APP_SERVER_SOCK` wins, else `CODEX_HOME`), and `status` reports the effective path and which variable won.
  180. Fail-open runs only before any stdin byte is consumed and no daemon payload was committed to stdout: the wrapper preflights the daemon socket (3 s deadline) and runs the bridge as a child — never `exec` — passing one-shot startup configuration, sign-out, help, version, and non-`app-server` requests to the real standalone `codex`, and falling back on every preflight failure or pre-session bridge failure (exit 1), always on pristine stdio+stdout. The bridge's connect + WebSocket-upgrade handshake runs under one absolute monotonic deadline (`CODEX_BRIDGE_CONNECT_TIMEOUT`, default 10 s) requiring `HTTP/1.1 101` plus a matching `Sec-WebSocket-Accept` (a `200` fails even with a valid hash), and a first-response deadline (`CODEX_BRIDGE_FIRST_MESSAGE_TIMEOUT`, default 30 s) bounds connect-to-matching-daemon-response covering the first RPC — an unrelated notification or foreign response never satisfies it, only the matching response/error (or timeout) clears it — preflight (3 s) + upgrade (10 s) + first RPC (30 s) stays far below a daemon-lock hang, and preflight and upgrade leave stdin untouched. Reads after a successful init block with no timeout so healthy idle sessions survive silence; every mid-session socket send and stdout write runs under its own write budget (`CODEX_BRIDGE_IO_TIMEOUT`, default 30 s), so a wedged or non-reading peer cannot hang Desktop. The commit point is byte-precise on input OR output, committed before the stdout write: the bridge counts every stdin byte read (buffered readahead included, even an unforwarded blank line) and marks stdout used before writing any forwarded daemon payload via a bounded write, so the fallback only ever runs on truly pristine stdio+stdout. Buffered EOF-tail data flushes before the WS Close. A mid-session bridge failure (exit 2+) makes the wrapper exit promptly so Desktop reconnects; the fallback never runs on half-consumed stdin or dirty stdout. The wrapper never starts the daemon on the spawn path (a wedged daemon lock must not block Desktop) — upkeep belongs to the LaunchAgent login script and install, which share one `CODEX_HOME` for the GUI domain and the daemon they start; if the socket is absent, Desktop simply runs stock Codex until the daemon is started.
  181. Residual risks, stated honestly: requests without both matching thread and turn IDs remain unanswered; a Codex client must handle those requests. A daemon that speaks framing-valid but semantically unexpected JSON-RPC (unknown methods, id-less responses) is treated as transport; pins are to app-server schema 0.158.0. The bridge trusts the local control socket; a malicious local daemon could hold the session up to the stated budgets, not past them.
  182. After upgrading `gbot`, existing shim users must re-run `gbot codex desktop-shim install` and fully quit and relaunch ChatGPT to refresh the installed scripts. EOF without any consumed input or committed output falls back to the real CLI instead of counting as a served session.
  183. Current shim limitation: Desktop's spawn-time app-tools MCP `-c` overrides are not forwarded to the already-running managed daemon. No restoration path or app-tools parity has been demonstrated here; this is not a claim of permanent protocol impossibility. Fully quit and relaunch ChatGPT.app after install (or login) so it inherits `CODEX_CLI_PATH`. `status` reads the macOS GUI-domain value via `launchctl getenv` (what Desktop actually inherits) alongside the calling shell's value. LaunchAgent persistence is macOS-first; elsewhere install still writes the wrapper and bridge but leaves `CODEX_CLI_PATH` for you to export. `~/.codex/bin` holds scripts only — there is no extra revert note to clean up; revert is `gbot codex desktop-shim uninstall` plus this section.
  184. **ChatGPT Desktop over CDP (scaffold).** Prefer the Desktop UI surface via Chrome DevTools Protocol when you need more than the app-server socket. CDP is **local-only** (`127.0.0.1`); there is no remote transport. Relaunch the macOS app with a debug port (Electron fuses block Node inspect, not Chromium's flag):
  185. ```sh
  186. osascript -e 'tell application "ChatGPT" to quit' \
  187. && open -a /Applications/ChatGPT.app --args --remote-debugging-port=9222
  188. gbot chatgpt-desktop status
  189. gbot chatgpt-desktop threads --limit 20
  190. gbot chatgpt-desktop search "launch"
  191. gbot chatgpt-desktop read <threadId>
  192. gbot chatgpt-desktop read <threadId> --full --limit 200
  193. gbot chatgpt-desktop send --project Launch "hello"
  194. gbot chatgpt-desktop send --thread-id <threadId> "hello"
  195. ```
  196. MCP tools: `chatgpt_desktop_status`, `chatgpt_desktop_list_threads`, `chatgpt_desktop_search_threads`, `chatgpt_desktop_read_thread`, `chatgpt_desktop_send`, `chatgpt_desktop_wait_reply`. List/search/read prefer the Codex app-server (`thread/list` with `modelProviders: []`, `thread/read` + `thread/turns/list`; never `thread/resume` for reads). Send / new-thread / wait / selected-thread stay on CDP; DOM read is fallback only. Desktop `local:<conversationId>` strips to the bare app-server id. Results report `backend: "cdp" | "app-server"`. Details: [docs/chatgpt-desktop-cdp.md](docs/chatgpt-desktop-cdp.md).
  197. **Status contract (`gbot codex status --json`).** `reachable` is endpoint reachability only. `socketState` is `socket`, `absent`, `permission-denied`, or `not-a-socket`; `mode` is `daemon` for a usable daemon, otherwise the failure: `socket-absent`, `permission-denied` (the file or the connect refused this user), `not-a-socket`, `connect-failed` (socket present, nothing completed the WebSocket upgrade), `handshake-failed` (upgrade or `initialize` failed), `windows-unsupported`, or `bad-response` (reachable, but `initialize` returned something off-schema — `reachable` stays `true`). `schema.compatibility` is `exact` when the daemon reports the pinned version, `unverified` when it differs (methods usually survive upgrades, but the shapes are not re-checked), or `unknown`. `cliVersionProbe` reports whether `codex --version` answered (`ok`, `missing`, `timeout` after 3 s, `error`). The document is always written to stdout and includes `exitCode`; it is `0` only for a usable daemon.
  198. `desktopShimConfigured` is true when the installed wrapper is selected by Desktop-facing `CODEX_CLI_PATH` (the GUI domain on macOS). This describes configuration for future launches; a running Desktop may not have inherited it, and the wrapper may have fallen back to stock Codex. `desktopAttached` is `"private-stdio"` when a Desktop-bundled app-server process is observed, otherwise `"unknown"`. That process observation and shim configuration can both be present. Neither a configured shim nor a reachable daemon proves Desktop is attached to that daemon. Verify actual attachment with a controlled shared-thread interaction and matching thread/turn IDs.
  199. **Thread discovery.** `list-threads` is newest-activity-first (`--sort updated`, the default; `--sort created|recency`, `--order asc`) and finds old-but-active threads: `--query zerofs` (case-insensitive name/title, preview or id prefix, scanning every page, not just the first 100), `--active-within 7d` / `--since 2026-09-01`, `--cwd`, `--model-provider`, `--source-kind`, `--archived`; the `codex_threads` MCP tool takes the same fields (`query`, `activeWithin`, `since`, `sort`, `order`, ...). `--limit N` (1–200) is the page size and pages with the opaque `--cursor` from the previous `nextCursor`; JSON keeps the cursor verbatim, text output prints a sanitized `more: --cursor …` hint. Requests pass `modelProviders: []` so threads from every provider appear (the daemon otherwise filters to the current provider) and `useStateDbOnly: true` for a fast state-DB listing, falling back to a full scan when that first page is empty. Text fields are stripped of terminal control sequences in both outputs (single-line fields also lose line breaks; `preview` keeps its newlines; a structured `source` such as `{ "custom": … }` passes through unchanged), `status` is one of `notLoaded | idle | active | systemError | unknown`, and non-numeric `updatedAt` / `createdAt` become `null`. Extra fields when present: `section`, `projectId`, `modelProvider`, `model`, `originator`. Unknown arguments are rejected before the socket is touched; a response that does not match the pinned schema (including an entry without a string `id`) fails with `reason: "bad-response"`. With client-side filters (`--query`, `--since`, `--active-within`) a page can hold more matches than `--limit`; `nextCursor` is then a `gbot1:` cursor that resumes inside that page, so nothing repeats or is skipped.
  200. **Routes, attribution, and loops.** `gbot codex send` runs on the machine that owns `CODEX_HOME`, as the user who owns the socket, with that user's Codex credentials; the socket path comes only from `CODEX_HOME` or `CODEX_APP_SERVER_SOCK`, never from the message or an agent-supplied argument. gbot has no remote transport. A cloud-hosted Grok Bot on the box cannot reach a desktop socket at `/home/box/.codex/...` — use Grok Bot Shell with a machineId to run `gbot` on the user's registered machine (after `codex app-server daemon start` / bootstrap there). `GROK_BOT_CODEX_THREADS=id,id` lets the operator pin `send` to approved threads (`reason: "route-not-allowed"` otherwise). Every send gets a delivery envelope: `messageId` (also sent as Codex's native `clientUserMessageId`), `correlationId` (defaults to the message id), optional `replyTo`, and `hop`. A reply passes the original correlation id and `hop` + 1:
  201. ```sh
  202. gbot codex send <threadId> "Grok here: build is green" # receipt: messageId M, correlationId M, hop 0
  203. gbot codex send --correlation-id M --reply-to M --hop 1 <threadId> "ack" # the answer, one hop later
  204. ```
  205. Sends at `hop >= GROK_BOT_MAX_HOPS` (default 4) are refused with `reason: "hop-limit"` before anything reaches the daemon, so two agents cannot acknowledge each other forever; `gbot` never auto-acknowledges. `--envelope` (implied by any envelope flag) prepends a one-line `[gbot msg=… corr=… reply-to=… hop=… from=user@host]` header so the receiving agent can quote the ids back. That header is caller-authored provenance for the reader, not authentication: the daemon authenticates the local user through the socket, nothing else. Private ChatGPT Desktop pipes and arbitrary ChatGPT chats stay out of scope; only Codex threads on a reachable app-server daemon are routes.
  206. **Busy threads.** `send` reads the thread status on resume. Only `idle` and `notLoaded` threads start a turn. An `active` thread (a turn in progress, or waiting on approval / user input) is refused with `reason: "busy"`: in app-server 0.158.0 a `turn/start` on an active thread steers that turn rather than queueing behind it, by default. Explicit guarded steering and managed bridge routes can deliver into active work; they never interrupt a turn. Either wait for `list-threads` to show `idle` and resend, or pass `--when-busy queue` to hand the message to the daemon's own queue through Codex's experimental `thread/queue/add` — that needs `GROK_BOT_CODEX_EXPERIMENTAL=1`, returns `delivery: "queued"` with `queuedSubmissionId`, and `gbot codex queue <threadId>` shows what is still waiting. `systemError` threads are refused with `reason: "thread-error"` (usually an unhealthy daemon; `gbot codex status`, and on macOS check the daemon's open-file count — the login script now starts it with a raised limit), statuses this version does not know with `reason: "unknown-status"`. Receipts distinguish `delivery: "accepted"` (turn started; `turnId`, `turnStatus`), `"queued"`, `"rejected"` (nothing was sent; see `reason`), and `"unknown"` (the request left but no acknowledgment came back — look for `messageId` in the thread or queue before resending). The decision record, with the schema evidence and a live probe of the queue API, is in [`docs/codex-busy-threads.md`](docs/codex-busy-threads.md).
  207. **Failure modes.** Every `send` and `codex` outcome under `--json` is one document on stdout with `exitCode`; failures include `{ error, delivery, reason, messageId, correlationId, hop, exitCode: 1, … }` and the process exits 1. Framework argument/schema errors remain on stderr and exit 2. `--json` is reserved anywhere before `--`; put `--` before flag-like message text. `reason` values are stable:
  208. - `socket-absent` / `permission-denied` / `not-a-socket` / `connect-failed` / `handshake-failed` / `windows-unsupported`: the route is unavailable. Start the daemon on the user's machine (`codex app-server daemon start` / bootstrap), fix the socket, or wait for the upstream Desktop fixes. On a Grok Bot box (`HOME=/home/box`), the error explains that gbot has no remote transport and to run `gbot` via Grok Bot Shell with a machineId instead of expecting a box-local Codex socket.
  209. - `unknown-thread`: use `list-threads`.
  210. - `external-owner`: a thread with an active writer (VS Code, TUI) is open in another client; close it there first.
  211. - `busy` / `thread-error` / `unknown-status`: see above.
  212. - `route-not-allowed` / `hop-limit` / `experimental-disabled`: refused by operator policy, the relay bound, or the experimental-API gate.
  213. - `unsupported`: the daemon does not offer the (experimental) method `--when-busy queue` needs.
  214. - `approval-refused` (`delivery: "accepted"`): `gbot` never approves commands or file changes on your behalf. If Codex asks while `gbot` is still connected, `send` refuses the request, exits 1, and tells you the turn id. Refusal replies are armed only once `gbot`'s own `turn/start` is in flight and only for requests naming that thread/turn — an approval outstanding from another client's turn (notably ChatGPT Desktop's) during resume, a busy reject, or a queue add is recorded but never answered, and a request naming another thread or Desktop turn inside the window is foreign-silent, so `gbot` cannot reject Desktop's approval. A request naming a turn that arrives before the acknowledgment supplies `gbot`'s turn id waits instead of being classified foreign, and is answered only on a match. Requests with missing thread or turn IDs remain unanswered because ownership cannot be established. `send` disconnects as soon as the turn starts, so later approval requests stay with the daemon for a Codex client to answer; for unattended sends set `approval_policy = "never"` in the daemon's `config.toml`.
  215. - `transport` / `bad-response` (`delivery: "unknown"`): the connection dropped or the daemon answered off-schema after the request left.
  216. ## Talking to Grok Bot from Codex
  217. The npm package is also an [Agent Bundle](https://scriptedalchemy.github.io/agent-bundle/) plugin
  218. that gives Codex, Claude Code, and Cursor a `grok-bot` MCP server with messaging,
  219. Codex conversation, and managed bridge tools, plus a `talk-to-grok-bot` skill.
  220. `gbot_send` and `gbot_thread` handle Grok conversations; `codex_threads`,
  221. `codex_send`, `codex_new`, `codex_wait`, and `codex_watch` handle Codex conversations.
  222. `chatgpt_desktop_*` tools drive ChatGPT Desktop over local CDP (with app-server
  223. fallback). Claude Code and Cursor bundles also include `/gbot:codex-send`,
  224. `/gbot:codex-threads`, and `/gbot:codex-wait` commands under `commands/`.
  225. `gbot_bridge_start`, `gbot_bridge_status`, `gbot_bridge_stop`, and
  226. `gbot_codex_respond` manage automatic delivery and scoped operator responses.
  227. The tools bundle this repository's gateway client and worker, so the installed
  228. plugin does not need `gbot` on `PATH`.
  229. **Replying to a Codex sender.** Messages a Codex thread sends to Grok Bot
  230. (`gbot_send` with a native or explicit `codexThreadId`, the managed bridge, its
  231. returned answers, and `gbot send` run inside a Codex terminal via `$CODEX_THREAD_ID`)
  232. start with `[from Codex thread <id> @ <machine>, cwd <cwd>; reply: codex_send({threadId:"<id>", message:"..."}) via MCP on <machine> (or CLI: gbot codex send <id> "...")]`.
  233. `<machine>` is the real hostname (`GROK_BOT_MACHINE_NAME` overrides); unknown fields are left out but the thread id never is.
  234. Find a thread to answer with `codex_threads` (`query`, `activeWithin`, newest activity first).
  235. Install the committed bundle directly from GitHub without cloning or building it:
  236. ```sh
  237. codex plugin marketplace add ScriptedAlchemy/grok-bot-cli
  238. codex plugin add gbot@gbot-marketplace
  239. claude plugin marketplace add ScriptedAlchemy/grok-bot-cli
  240. claude plugin install gbot@gbot-marketplace
  241. ```
  242. Cursor users can add `https://github.com/ScriptedAlchemy/grok-bot-cli` as a
  243. marketplace repository from Customize → Plugins. The repository-root host
  244. marketplaces all point at the committed `artifact/` bundle.
  245. Install the bundled host projections from the same npm package:
  246. ```sh
  247. gbot-install install codex
  248. gbot-install install claude
  249. gbot-install install cursor
  250. gbot-install install grokbot
  251. gbot-install doctor
  252. ```
  253. Add `--replace` to an install command to overwrite an existing copy. The bundle is
  254. registered as `gbot`.
  255. `gbot-install install grokbot` stages the Cursor projection as a marketplace
  256. repository under `~/.grokbot/agent-bundle/marketplaces/gbot` (`GROK_BOT_HOME`
  257. overrides `~/.grokbot`). On the Grok Bot computer it also sideloads gbot into Grok
  258. Bot's existing clone of the `scriptedalchemy/plugins` marketplace: it adds `gbot/`
  259. and a `marketplace.json` entry under the clone commit Grok Bot already uses, and
  260. writes `plugins/cache/scriptedalchemy-plugins/gbot/<commit>/` with `.cache-complete`.
  261. Every path it writes is recorded in the install receipt, and `uninstall grokbot`
  262. removes exactly those paths. `--json` reports the outcome in its `sideload` field.
  263. | Option | Environment | Default |
  264. | --- | --- | --- |
  265. | `--sideload-repo <owner/repo>` | `GROK_BOT_SIDELOAD_REPO` | `scriptedalchemy/plugins` |
  266. | `--sideload-slug <slug>` | `GROK_BOT_SIDELOAD_SLUG` | `<owner>-<repo>` (`scriptedalchemy-plugins`) |
  267. | `--no-sideload` | `GROK_BOT_SIDELOAD=0` | sideload on |
  268. | | `GROK_BOT_AGENT_DATA_DIR` | first of `/home/box/agent-data`, `~/.grokbot/agent-data`, `~/Library/Application Support/Grok Bot/agent-data` with a `plugins/` folder |
  269. `GROK_BOT_SIDELOAD_MARKETPLACE` from 0.12.3 is still read but must name one
  270. repository; prefer `GROK_BOT_SIDELOAD_REPO`. The next install or uninstall removes
  271. the 0.12.3 sideload record. `gbot-install doctor --host grokbot` reports the Grok Bot
  272. plugin id (`AB7334`) and the sideload state (`AB7335`). Grok Bot keeps the sideloaded
  273. cache copy only while its account plugin listing names gbot; for a durable install,
  274. add gbot from the `ScriptedAlchemy/plugins` marketplace in Grok Bot.
  275. `gbot_thread` returns a small receipt by default: deterministic `summary`, opaque
  276. `cursor`, `entryCount`, and `gapReset`.
  277. Pass the cursor back as `after` for an exclusive client-side delta. Pass `full:true`
  278. only when bounded entry bodies are needed in structured content; `Agent.Text` remains
  279. the short summary. Unknown cursors set `gapReset: true`; repeat that call with
  280. `full:true` to inspect the bounded reset snapshot.
  281. Auth resolves exactly as for `gbot`: `GROK_BOT_GATEWAY_URL` + `GROK_BOT_GATEWAY_TOKEN`,
  282. then the Grok Bot cached gateway session, then `CURSOR_ACCESS_TOKEN`, then the active Grok Bot account credentials. The MCP server therefore
  283. needs outbound HTTPS to the gateway host and read access to the app-session file
  284. (`~/.config/Grok Bot` on Linux, `~/Library/Application Support/Grok Bot` on macOS).
  285. A sandbox that blocks network egress or hides the home directory makes `gbot_send`
  286. fail with the gateway error; run `gbot doctor` inside the same sandbox to see which
  287. credential source is visible.
  288. For on-disk `--files` mode, pass `--dir` or set `GROK_BOT_AGENTS_DIR`.
  289. To route a repository's agents to a bot by default, add a note to its `AGENTS.md`:
  290. ```md
  291. ## Grok Bot
  292. Use the `grok-bot` MCP tools to coordinate with Grok Bot. Send questions and
  293. handoffs to the `General` bot with `gbot_send` (first line: who you are and what
  294. you need), then read the reply with `gbot_thread`. Do not block a turn waiting
  295. for it.
  296. ```
  297. ## Local history
  298. Recording is **opt-in**. Set `GROK_BOT_HISTORY=on` (or `true`/`1`) to append successful
  299. `send`/`thread` observations as plaintext JSONL at
  300. `~/.grok-bot-cli/history.jsonl`. Without that env, nothing is written.
  301. ```bash
  302. export GROK_BOT_HISTORY=on
  303. gbot send Researcher "Investigate the startup timeout"
  304. gbot thread Researcher
  305. gbot history Researcher --search timeout
  306. gbot history --path
  307. ```
  308. `history` works offline. Use `--history-dir` / `GROK_BOT_HISTORY_DIR` to relocate,
  309. `--no-history` to skip one command. New dirs are `0700`, files `0600`. Conversation
  310. text is recorded as you typed it; gateway credentials and raw response metadata are not.
  311. ## License
  312. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.