/grok-runtime

name: grok-runtime
description: Internal helper contract for calling the grok-companion runtime from Claude Code or Codex. Reference when invoking the Grok companion script or the grok_search MCP tool.

Grok companion runtime

The Grok plugin wraps the local `grok` CLI's **headless mode** (`grok -p "<prompt>" --output-format json`). Grok manages its own session store under `~/.grok/sessions`, so the plugin does not run a separate server or broker.

Always invoke through the companion script so job tracking, prompt shaping, and tool filtering stay consistent:

node "${CLAUDE_PLUGIN_ROOT}/scripts/grok-companion.mjs" <subcommand> [flags] [text]

Or, for live search from any MCP-capable agent, call the `grok_search` tool (auto-wired when the plugin is installed; otherwise `npx -y grok-build-x-search-mcp`).

When to use Grok (routing guidance for host agents)

| Need | Prefer | | --- | --- | | Live X sentiment, breaking news, "what are people saying" | `grok_search` / `/grok:search` | | Current package/version/docs facts beyond training cutoff | `grok_search` / `/grok:search` | | Second opinion code review on a diff | `/grok:review` | | Substantial implement/debug pass with write access | `/grok:rescue` or `grok:grok-rescue` subagent | | Trivial local edit the host can do in one step | **Do not** delegate — handle inline |

Subcommands

| Subcommand | Purpose | Tool surface | | --- | --- | --- | | `setup [--json]` | Check install + login (no API call) | none | | `review [--base <ref>] [--background] [--model <m>] [focus]` | Read-only code review of a git diff | denylist of write/shell/MCP/media; `--sandbox read-only` | | `task <text> [--background] [--resume-last\|--fresh] [--read-only] [--model <m>] [--effort <low\|medium\|high>]` | Delegate work; write-capable by default | full (or read-only with `--read-only`) | | `search <query> [--background] [--model <m>]` | Live X/web search | same safe profile as review (web tools kept) | | `status [--job <id>]` | List or show jobs | n/a | | `result [--job <id>]` | Final output + Grok session id | n/a | | `cancel [--job <id>]` | Cancel a running job | n/a |

Tool filtering note (CLI bug)

On grok-cli **0.2.x**, `grok -p ... --tools <allowlist>` often fails session creation when web tools or shell are involved (`Requirements unsatisfied` / `run_terminal_cmd` / `auto_background_on_timeout`). This plugin **never** uses `--tools` for search/review; it uses `--disallowed-tools` + `--sandbox read-only` + `--no-subagents`, and disables vendor MCP imports in the child env to prevent recursive `grok_search` fork-bombs.

Key facts

• Add `--json` to any command for machine-readable output.
• The JSON contract from `grok -p` is `{ text, stopReason, sessionId, requestId, thought }`.
• Sessions: `-s <id>` creates a **new** session id, `-r <id>` resumes, `-c` continues most recent in cwd. The companion handles this via `--resume-last`.
• Background jobs write streaming-json to a per-repo log under `~/.grok/cc-plugin/jobs/`; `status`/`result` read from there.
• Models available locally: run `grok models`. Default is `grok-build`.
• `GROK_BIN` overrides the binary path; `GROK_CC_STATE_DIR` overrides the job state directory (used in tests).
• Always return the companion's stdout verbatim to the user. Do not paraphrase.