fix: Codex/Claude tools target user machines, not the Grok Bot box (#112)

* fix: point Codex/Claude tools at user machines, not the box

When the Grok Bot sandbox has no local Codex socket, errors and plugin
docs now explain that sessions live on the user's registered computers
and how to target them via CODEX_APP_SERVER_SOCK or a local bridge.

Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>

* fix: box agents use Grok Bot Shell, not remote sockets

gbot only dials a local Codex/Claude Unix socket. On HOME=/home/box, tell
agents not to call those tools — run gbot on the user's machine via Grok Bot
Shell with a machineId after daemon start/bootstrap. Drop SSH/remote guidance.

Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>

* chore: rebuild artifact after guidance module trim

Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>

Author: ScriptedAlchemy

.changeset/user-machine-codex-claude.md

@@ -0,0 +1,5 @@
+---
+"grok-bot-cli": patch
+---
+
+Tell Grok Bot agents that Codex/Claude tools use local sockets only: on the box, do not call them — run `gbot` on the user's machine via Grok Bot Shell with a machineId after `codex app-server daemon start` / bootstrap. No remote transport.

.claude-plugin/marketplace.json

@@ -1 +1 @@
-{"description":"Message Grok Bot from Codex, Claude Code, and Cursor, with managed automatic replies and explicit Codex conversation links.","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, with managed automatic replies and explicit Codex conversation links.","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.10.0"}]}
+{"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.10.0"}]}

.cursor-plugin/marketplace.json

@@ -1 +1 @@
-{"name":"gbot-marketplace","owner":{"name":"gbot"},"plugins":[{"description":"Message Grok Bot from Codex, Claude Code, and Cursor, with managed automatic replies and explicit Codex conversation links.","name":"gbot","source":"./artifact"}]}
+{"name":"gbot-marketplace","owner":{"name":"gbot"},"plugins":[{"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","source":"./artifact"}]}

README.md

@@ -66,6 +66,11 @@ so this integration needs no desktop shim. The Claude plugin includes an opt-in
 `claude-channel` MCP server; Codex and Grok callers can use `claude_send`, or the
 local CLI, to send a message and receive Claude's explicit reply.
 
+Claude channels live on the **user's registered machine** (the same host that runs
+Claude Code), not on the Grok Bot agent box (`HOME=/home/box`). gbot has no remote
+transport: from the box, use Grok Bot Shell with a machineId to run
+`gbot claude send` on that computer. Auth stays with that machine's native Claude login.
+
 After installing this version of the Claude plugin, launch a named session:
 
 ```sh
@@ -198,6 +203,8 @@ gbot codex send <threadId> "Grok here: the build is green, please continue."
 
 **Which Codex you reach.** `gbot` connects to `$CODEX_HOME/app-server-control/app-server-control.sock` (default `~/.codex/...`) 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.
 
+**User machines, not the Grok Bot box.** 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.
+
 **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.
 
 **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.
@@ -222,7 +229,7 @@ Current shim limitation: Desktop's spawn-time app-tools MCP `-c` overrides are n
 
 **Thread discovery.** `list-threads --limit N` (1–200) pages with the opaque `--cursor` from the previous `nextCursor`; JSON keeps the cursor verbatim, text output prints a sanitized `more: --cursor …` hint. 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` becomes `null`. 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"`.
 
-**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`, never from the message or an agent-supplied argument. A cloud-hosted Grok Bot cannot reach a desktop socket directly — run `gbot` locally (for example from a Codex skill or an agent on that machine). `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:
+**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:
 
 ```sh
 gbot codex send <threadId> "Grok here: build is green"                  # receipt: messageId M, correlationId M, hop 0
@@ -235,7 +242,7 @@ Sends at `hop >= GROK_BOT_MAX_HOPS` (default 4) are refused with `reason: "hop-l
 
 **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:
 
-- `socket-absent` / `permission-denied` / `not-a-socket` / `connect-failed` / `handshake-failed` / `windows-unsupported`: the route is unavailable. Start the daemon, fix the socket, or wait for the upstream Desktop fixes.
+- `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.
 - `unknown-thread`: use `list-threads`.
 - `external-owner`: a thread with an active writer (VS Code, TUI) is open in another client; close it there first.
 - `busy` / `thread-error` / `unknown-status`: see above.

agent-bundle.config.ts

@@ -11,7 +11,7 @@ export default defineConfig({
   output: { distPath: 'artifact', repositoryMarketplace: true },
   plugin: {
     description:
-      'Message Grok Bot from Codex, Claude Code, and Cursor, with managed automatic replies and explicit Codex conversation links.',
+      '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.',
     // plugin.name is also the routed bin name: `dist/bin/gbot.mjs`.
     name: 'gbot',
   },

artifact/.claude-plugin/marketplace.json

@@ -1 +1 @@
-{"description":"Message Grok Bot from Codex, Claude Code, and Cursor, with managed automatic replies and explicit Codex conversation links.","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, with managed automatic replies and explicit Codex conversation links.","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":"./","version":"0.10.0"}]}
+{"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":"./","version":"0.10.0"}]}

artifact/.claude-plugin/plugin.json

@@ -1 +1 @@
-{"author":{"name":"gbot"},"channels":[{"server":"claude-channel"}],"description":"Message Grok Bot from Codex, Claude Code, and Cursor, with managed automatic replies and explicit Codex conversation links.","name":"gbot","version":"0.10.0"}
+{"author":{"name":"gbot"},"channels":[{"server":"claude-channel"}],"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","version":"0.10.0"}

artifact/.codex-plugin/plugin.json

@@ -1 +1 @@
-{"author":{"name":"Zack Jackson","url":"https://github.com/ScriptedAlchemy"},"description":"Message Grok Bot from Codex, Claude Code, and Cursor, with managed automatic replies and explicit Codex conversation links.","homepage":"https://github.com/ScriptedAlchemy/grok-bot-cli#readme","interface":{"capabilities":["mcp","skills"],"category":"Productivity","defaultPrompt":["Help me use gbot."],"developerName":"gbot","displayName":"gbot","longDescription":"Message Grok Bot from Codex, Claude Code, and Cursor, with managed automatic replies and explicit Codex conversation links.","shortDescription":"Message Grok Bot from Codex, Claude Code, and Cursor, with managed automatic replies and explicit Codex conversation links."},"keywords":["grok","grok-bot","grokbot","gbot","cursor","ai-agents","automation","terminal","cli","agent-bundle"],"license":"MIT","mcpServers":"./.codex-plugin/mcp.json","name":"gbot","repository":"https://github.com/ScriptedAlchemy/grok-bot-cli","skills":"./skills/","version":"0.10.0"}
+{"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","interface":{"capabilities":["mcp","skills"],"category":"Productivity","defaultPrompt":["Help me use gbot."],"developerName":"gbot","displayName":"gbot","longDescription":"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.","shortDescription":"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."},"keywords":["grok","grok-bot","grokbot","gbot","cursor","ai-agents","automation","terminal","cli","agent-bundle"],"license":"MIT","mcpServers":"./.codex-plugin/mcp.json","name":"gbot","repository":"https://github.com/ScriptedAlchemy/grok-bot-cli","skills":"./skills/","version":"0.10.0"}

artifact/.cursor-plugin/marketplace.json

@@ -1 +1 @@
-{"name":"gbot-marketplace","owner":{"name":"gbot"},"plugins":[{"description":"Message Grok Bot from Codex, Claude Code, and Cursor, with managed automatic replies and explicit Codex conversation links.","name":"gbot","source":"./"}]}
+{"name":"gbot-marketplace","owner":{"name":"gbot"},"plugins":[{"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","source":"./"}]}

artifact/.cursor-plugin/plugin.json

@@ -1 +1 @@
-{"author":{"name":"Zack Jackson"},"description":"Message Grok Bot from Codex, Claude Code, and Cursor, with managed automatic replies and explicit Codex conversation links.","displayName":"gbot","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","mcpServers":"./.cursor-plugin/mcp.json","name":"gbot","repository":"https://github.com/ScriptedAlchemy/grok-bot-cli","skills":"./skills/","version":"0.10.0"}
+{"author":{"name":"Zack Jackson"},"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.","displayName":"gbot","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","mcpServers":"./.cursor-plugin/mcp.json","name":"gbot","repository":"https://github.com/ScriptedAlchemy/grok-bot-cli","rules":"./rules/","skills":"./skills/","version":"0.10.0"}