grok-bot-cli 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # grok-bot-cli
 
+## 0.10.1
+
+### Patch Changes
+
+- 3508def: 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.
+
+## 0.10.0
+
+### Minor Changes
+
+- a619538: Add an opt-in native Claude Code channel, with private local messaging and correlated replies through `gbot claude send` and `claude_send`.
+
+### Patch Changes
+
+- 75521df: Update agent-bundle to the 0.3.1 release preview (899755dc6d) and rebuild the plugin artifact.
+- 3f64ac2: Update agent-bundle to b4e38409f4 so generated executables no longer ship bundled dependencies' comments.
+- 872eb61: Reduce the messaging skill's default context by loading bridge administration and diagnostic procedures only when needed.
+- 657ed43: Update the Claude channel MCP server SDK to 2.1.0.
+
+## 0.9.1
+
+### Patch Changes
+
+- f2482eb: Build the plugin with the agent-bundle 0.3.0 pkg.pr.new preview (4f62216f30).
+- c49a0b8: Ship generated host marketplaces and the complete Agent Bundle artifact in the GitHub repository so Codex, Claude Code, and Cursor can install it without a local build.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -59,6 +59,50 @@ Options are command-local (for example, `gbot send --history-dir DIR ...`);
 a JSON document on stdout with `exitCode` (see below), every other command
 prints the failure message on stderr and exits 1.
 
+## Messaging a live Claude Code session
+
+Claude Code has a native [Channels API](https://code.claude.com/docs/en/channels-reference),
+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
+GROK_BOT_CLAUDE_CHANNEL=review claude --dangerously-load-development-channels plugin:gbot@gbot-marketplace
+# From another terminal on the same machine and user account:
+gbot claude send review "Reply with GBOT_CLAUDE_OK" --json
+```
+
+Accept Claude's development-channel prompt. Custom channels are a research preview
+and require session opt-in and any applicable organization policy. Claude must be
+signed in. The development flag permits this channel; it does not bypass tool
+approvals. `claude_send` takes `name`, `message`, and optional `timeoutMs` (default
+60000, maximum 120000). Claude uses `claude_reply` with the incoming `request_id`.
+Only that explicit reply completes the call; a notification alone is not proof
+Claude received or processed the message. Timeout/disconnect returns `unknown`;
+do not automatically resend.
+
+Each name selects one live session. Sockets live under `~/.grok-bot-cli/claude/`
+in a user-owned 0700 directory, with mode 0600 sockets. Access grants messaging
+to local processes running as the same user. No TCP listener, automatic permission
+approval, conversation-history scraping, or background daemon is installed.
+Without `GROK_BOT_CLAUDE_CHANNEL`, the channel is disabled. Shut down the owning
+Claude session to close it. A crashed process may leave a socket: confirm the
+named session is stopped before removing that socket and restarting. A second
+session with the same name fails rather than taking over the first.
+
+This targets opted-in Claude Code sessions, not arbitrary existing sessions or
+ordinary Claude Desktop chats. Remote Grok runtimes need local tool execution to
+reach the socket; installing an MCP artifact does not establish that connection.
+Claude can use the existing `gbot_send`/`gbot_thread` and `codex_send` tools for
+outgoing messages; its own tool permissions still apply.
+
 ## Automatic Grok ↔ Codex replies
 
 In a native Codex invocation, `gbot_send` sends once and returns a durable exchange
@@ -159,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.
@@ -183,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
@@ -196,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.
@@ -217,6 +263,20 @@ Codex conversation, and managed bridge tools, plus a `talk-to-grok-bot` skill.
 The tools bundle this repository's gateway client and worker, so the installed
 plugin does not need `gbot` on `PATH`.
 
+Install the committed bundle directly from GitHub without cloning or building it:
+
+```sh
+codex plugin marketplace add ScriptedAlchemy/grok-bot-cli
+codex plugin add gbot@gbot-marketplace
+
+claude plugin marketplace add ScriptedAlchemy/grok-bot-cli
+claude plugin install gbot@gbot-marketplace
+```
+
+Cursor users can add `https://github.com/ScriptedAlchemy/grok-bot-cli` as a
+marketplace repository from Customize → Plugins. The repository-root host
+marketplaces all point at the committed `artifact/` bundle.
+
 Install the bundled host projections from the same npm package:
 
 ```sh

package/dist/.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.9.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.1"}]}

package/dist/.claude-plugin/plugin.json

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

package/dist/.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.9.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.1"}

package/dist/.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":"./"}]}

package/dist/.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.9.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.1"}

package/dist/.mcp.json

@@ -1 +1 @@
-{"mcpServers":{"grok-bot":{"args":["${CLAUDE_PLUGIN_ROOT}/mcp/mcp-grok-bot-b8c2461e.mjs"],"command":"node","env":{"AGENT_BUNDLE_PLUGIN_ROOT":"${CLAUDE_PLUGIN_ROOT}"},"type":"stdio"}}}
+{"mcpServers":{"claude-channel":{"args":["${CLAUDE_PLUGIN_ROOT}/mcp/mcp-claude-channel-8029413c.mjs"],"command":"node","env":{"AGENT_BUNDLE_PLUGIN_ROOT":"${CLAUDE_PLUGIN_ROOT}"},"type":"stdio"},"grok-bot":{"args":["${CLAUDE_PLUGIN_ROOT}/mcp/mcp-grok-bot-b8c2461e.mjs"],"command":"node","env":{"AGENT_BUNDLE_PLUGIN_ROOT":"${CLAUDE_PLUGIN_ROOT}"},"type":"stdio"}}}

package/dist/AGENTS.md

@@ -0,0 +1,12 @@
+# Agent instructions
+
+Publish exclusively through `.github/workflows/release.yml` with GitHub OIDC.
+Its package release script is a workflow entrypoint: never publish locally,
+request npm publishing tokens/login, or troubleshoot local publishing auth.
+Use the existing Changesets flow and verify Actions plus the registry before
+updating installations.
+
+Delete dead code, obsolete scripts, duplicate workarounds, and unused legacy
+installs. Check active owners/references first; preserve auth, operator env,
+durable data, and intentional duplicate suppression. Prefer existing helpers,
+stdlib, and native features over new wrappers or fallback frameworks.

package/dist/INSTALL.md

@@ -1,8 +1,8 @@
 # Install gbot
 
-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.
 
-Version: `0.9.0`
+Version: `0.10.1`
 
 Run these commands from this bundle directory. The bundle is self-contained: every command below is
 a host command or the bundled installer, and nothing requires the `agent-bundle` CLI. Where that CLI is
@@ -33,7 +33,7 @@ claude plugin install gbot@gbot-marketplace --scope user
 
 With the optional `agent-bundle` CLI, `agent-bundle install claude --from ./` runs this sequence
 automatically when the installed copy has the same version but a different content hash; `--replace`
-(alias `--force`) forces it.
+forces it.
 
 ### Uninstall
 
@@ -42,7 +42,7 @@ claude plugin uninstall gbot@gbot-marketplace --scope user --keep-data
 ```
 
 Match the scope the plugin was installed with (`user`, `project`, or `local`). `--keep-data` keeps durable
-runtime state (Claude orphans the cached copy, `state/` included, for its ~14-day grace period); omit it to
+runtime state (Claude orphans the cached copy for its ~14-day grace period); omit it to
 remove `~/.claude/plugins/data/<id>/` immediately.
 
 The marketplace `gbot-marketplace` stays registered. Remove it only when nothing else installs from it:
@@ -61,9 +61,10 @@ would be removed and `agent-bundle uninstall claude --from ./` reverses the reco
 (or under `$CLAUDE_CONFIG_DIR`; `user` is the install scope, pass `--scope project` or `--scope local` to match
 a scoped install), and `uninstall` consumes it, running the two commands above in order and retaining the
 marketplace while any other plugin, scope, or project still installs from it. Durable runtime state
-is kept by default; `--purge-data --confirm-purge` removes `state/` and `~/.claude/plugins/data/<id>/`
-immediately. A missing receipt or a cached copy that no longer matches it is refused unless `--force`; a
-second run is a `not-installed` no-op.
+is kept by default; `--purge-data --confirm-purge` removes the receipt-owned state roots and
+`~/.claude/plugins/data/<id>/` immediately. A missing receipt or a cached copy that no longer matches it is refused unless `--force`;
+`--purge-data --confirm-purge` without a receipt is refused even with `--force` (`AB7009`); a second run is a
+`not-installed` no-op.
 
 ## Codex
 
@@ -92,7 +93,7 @@ or omits `enabled` (`AB7004`) and leaves that install unchanged. Enable the plug
 
 With the optional `agent-bundle` CLI, `agent-bundle install codex --from ./` runs this sequence
 automatically when the installed copy has the same version but a different content hash; `--replace`
-(alias `--force`) forces it.
+forces it.
 
 ### Uninstall
 
@@ -100,8 +101,7 @@ automatically when the installed copy has the same version but a different conte
 codex plugin remove gbot@gbot-marketplace
 ```
 
-Codex 0.147.0 deletes the cached plugin tree, `state/` included, on `plugin remove` and has no keep-data
-option.
+Codex 0.147.0 deletes the cached plugin tree on `plugin remove` and has no keep-data option.
 
 The marketplace `gbot-marketplace` stays registered. Remove it only when nothing else installs from it:
 `codex plugin list` shows every other plugin from it.
@@ -114,8 +114,10 @@ With the optional `agent-bundle` CLI, `agent-bundle uninstall codex --from ./ --
 would be removed and `agent-bundle uninstall codex --from ./` reverses the recorded registrations.
 `agent-bundle install codex` records a receipt at `~/.codex/agent-bundle/receipts/gbot.gbot-marketplace.user.json` (or
 under `$CODEX_HOME`), and `uninstall` consumes it, running the two commands above in order. `--keep-data`
-cannot preserve durable state on Codex; the result says so (`unavailable`). A missing receipt or a cached
-copy that no longer matches it is refused unless `--force`; a second run is a `not-installed` no-op.
+keeps the framework state roots the receipt records outside the cached tree (`kept`); with nothing there the
+result says so (`unavailable`). A missing receipt or a cached
+copy that no longer matches it is refused unless `--force`; `--purge-data --confirm-purge` without a receipt is
+refused even with `--force` (`AB7009`); a second run is a `not-installed` no-op.
 
 ## Cursor
 
@@ -137,37 +139,38 @@ manifest-declared `hooks/hooks.json` from that directory; plugin hooks run from
 The installer writes an install receipt (`.agent-bundle-install.json`: plugin, version, content hash,
 owned files) beside the plugin manifest. Re-running `node ./install.mjs` on an identical artifact
 is a no-op that says so. When the installed copy has the same version but different content, the
-installer replaces its owned files in place and leaves runtime state (`state/`) untouched:
+installer replaces its owned files in place and leaves unowned entries untouched:
 
 ```sh
 node ./install.mjs            # same-version content drift of a receipt-managed copy is replaced
-node ./install.mjs --replace  # also replace a different installed version, or adopt a pre-receipt copy
+node ./install.mjs --replace  # also replace a different installed version
 ```
 
-`--force` is an alias for `--replace`. A directory that is not an agent-bundle install of this
-plugin is always refused with an installed-versus-artifact content-hash comparison; remove it
-manually. The optional `agent-bundle` CLI applies the same policy through
+A directory without a receipt naming this plugin (including a copy placed before install receipts
+existed) is foreign and always refused with an installed-versus-artifact content-hash comparison;
+remove it manually and reinstall. The optional `agent-bundle` CLI applies the same policy through
 `agent-bundle install cursor --from ./ [--replace]`.
 
 ### Uninstall
 
 ```sh
 node ./install.mjs --uninstall --plan                        # print exactly what would be removed
-node ./install.mjs --uninstall                               # remove the receipt-owned files; keep state/
-node ./install.mjs --uninstall --purge-data --confirm-purge  # also remove durable runtime state
+node ./install.mjs --uninstall                               # remove the receipt-owned files; keep durable state
+node ./install.mjs --uninstall --purge-data --confirm-purge  # also remove receipt-owned durable runtime state
 node ./install.mjs --uninstall --mode marketplace            # remove a staged marketplace repository
 ```
 
 Uninstall removes exactly what the receipt owns: the listed files, the directories the installer
 created (including `~/.cursor/plugins/local` when the installer made it), and nothing else. Durable
-runtime state under `state/` (state kernel, notices journal) — and, for an Agent Plugins pack with a stdio
-server, the `~/.cursor/agent-bundle/plugin-data/<name>` directory the receipt records as `PLUGIN_DATA` — is kept
-unless `--purge-data --confirm-purge` is passed (a kept data directory leaves a remnant receipt behind so a later
-purge still finds it; an empty one is pruned); unowned files are left in place and listed. A supported older
-receipt with no recorded state location retains the current environment's default as unproven; a keep-data run
-cannot turn that observation into later purge authority. A directory without a receipt is refused unless
-`--force` (which removes a pre-receipt legacy copy by its inventory); owned content that no longer matches
-the receipt is refused unless `--force`; a directory that is not this plugin's install is always refused.
+runtime state (the framework state roots the receipt records with ownership evidence) — and, for an Agent
+Plugins pack with a stdio server, the `~/.cursor/agent-bundle/plugin-data/<name>` directory the receipt records
+as `PLUGIN_DATA` — is kept unless `--purge-data --confirm-purge` is passed (a kept data directory leaves a
+remnant receipt behind so a later purge still finds it; an empty one is pruned); unowned entries, including a
+`state/` directory beside the plugin, are left in place and listed. A receipt with no recorded state location
+(written before the install could record it) retains the current environment's default as unproven; a
+keep-data run cannot turn that observation into later purge authority. A directory without a receipt naming
+this plugin is foreign and always refused, with or without `--force`; owned content that no longer matches
+the receipt is refused unless `--force`.
 A second run is a `Not installed` no-op. With the optional `agent-bundle` CLI,
 `agent-bundle uninstall cursor --from ./ [--mode marketplace]` applies the same policy, and
 `agent-bundle doctor --from ./` shows the lifecycle stage (placed, registered, enabled, active) with
@@ -254,21 +257,21 @@ other clients; the recorded clients above name which of them expand the placehol
 ### Reinstall after a same-version rebuild
 
 The installer records an install receipt (`.agent-bundle-install.json`) and replaces its owned files in
-place when the same version was rebuilt with different content; runtime state (`state/`) is never
-touched. Pass `--replace` (alias `--force`) to replace a different installed version or to adopt a
-copy installed before receipts existed. Foreign directories are refused with a content-hash
-comparison. For a client that manages its own copy, remove and re-add the plugin through that client
-when only content changed at the same version.
+place when the same version was rebuilt with different content; unowned entries are never
+touched. Pass `--replace` to replace a different installed version. A directory without a receipt
+naming this plugin (including a copy installed before receipts existed) is foreign and refused with a
+content-hash comparison; remove it manually. For a client that manages its own copy, remove and re-add
+the plugin through that client when only content changed at the same version.
 
 ### Uninstall
 
 ```sh
 node ./install.mjs --uninstall --plan                        # print exactly what would be removed
-node ./install.mjs --uninstall                               # remove the receipt-owned files; keep state/
-node ./install.mjs --uninstall --purge-data --confirm-purge  # also remove durable runtime state
+node ./install.mjs --uninstall                               # remove the receipt-owned files; keep durable state
+node ./install.mjs --uninstall --purge-data --confirm-purge  # also remove receipt-owned durable runtime state
 ```
 
 Uninstall removes exactly what the receipt owns (files, installer-created directories) and keeps
-durable runtime state under `state/` (and the recorded `PLUGIN_DATA` directory of an Agent Plugins pack)
-unless `--purge-data --confirm-purge` is passed. A missing
-receipt or modified owned content is refused unless `--force`; foreign directories are always refused.
+the durable runtime state the receipt records (and the recorded `PLUGIN_DATA` directory of an Agent Plugins
+pack) unless `--purge-data --confirm-purge` is passed. Modified owned content is refused unless `--force`;
+a directory without a receipt naming this plugin is foreign and always refused.

package/dist/README.md

@@ -59,6 +59,50 @@ Options are command-local (for example, `gbot send --history-dir DIR ...`);
 a JSON document on stdout with `exitCode` (see below), every other command
 prints the failure message on stderr and exits 1.
 
+## Messaging a live Claude Code session
+
+Claude Code has a native [Channels API](https://code.claude.com/docs/en/channels-reference),
+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
+GROK_BOT_CLAUDE_CHANNEL=review claude --dangerously-load-development-channels plugin:gbot@gbot-marketplace
+# From another terminal on the same machine and user account:
+gbot claude send review "Reply with GBOT_CLAUDE_OK" --json
+```
+
+Accept Claude's development-channel prompt. Custom channels are a research preview
+and require session opt-in and any applicable organization policy. Claude must be
+signed in. The development flag permits this channel; it does not bypass tool
+approvals. `claude_send` takes `name`, `message`, and optional `timeoutMs` (default
+60000, maximum 120000). Claude uses `claude_reply` with the incoming `request_id`.
+Only that explicit reply completes the call; a notification alone is not proof
+Claude received or processed the message. Timeout/disconnect returns `unknown`;
+do not automatically resend.
+
+Each name selects one live session. Sockets live under `~/.grok-bot-cli/claude/`
+in a user-owned 0700 directory, with mode 0600 sockets. Access grants messaging
+to local processes running as the same user. No TCP listener, automatic permission
+approval, conversation-history scraping, or background daemon is installed.
+Without `GROK_BOT_CLAUDE_CHANNEL`, the channel is disabled. Shut down the owning
+Claude session to close it. A crashed process may leave a socket: confirm the
+named session is stopped before removing that socket and restarting. A second
+session with the same name fails rather than taking over the first.
+
+This targets opted-in Claude Code sessions, not arbitrary existing sessions or
+ordinary Claude Desktop chats. Remote Grok runtimes need local tool execution to
+reach the socket; installing an MCP artifact does not establish that connection.
+Claude can use the existing `gbot_send`/`gbot_thread` and `codex_send` tools for
+outgoing messages; its own tool permissions still apply.
+
 ## Automatic Grok ↔ Codex replies
 
 In a native Codex invocation, `gbot_send` sends once and returns a durable exchange
@@ -159,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.
@@ -183,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
@@ -196,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.
@@ -217,6 +263,20 @@ Codex conversation, and managed bridge tools, plus a `talk-to-grok-bot` skill.
 The tools bundle this repository's gateway client and worker, so the installed
 plugin does not need `gbot` on `PATH`.
 
+Install the committed bundle directly from GitHub without cloning or building it:
+
+```sh
+codex plugin marketplace add ScriptedAlchemy/grok-bot-cli
+codex plugin add gbot@gbot-marketplace
+
+claude plugin marketplace add ScriptedAlchemy/grok-bot-cli
+claude plugin install gbot@gbot-marketplace
+```
+
+Cursor users can add `https://github.com/ScriptedAlchemy/grok-bot-cli` as a
+marketplace repository from Customize → Plugins. The repository-root host
+marketplaces all point at the committed `artifact/` bundle.
+
 Install the bundled host projections from the same npm package:
 
 ```sh