/grok-runtime
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.
$ npx -y skills add VasiHemanth/grok-build-plugin --skill grok-runtime --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/grok-runtime
Context preview
The summary Claude sees to decide when to auto-load this skill.
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.
SKILL.md
grok-runtime.SKILL.mdname: 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.
Read more
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.
Want Claude Code, Codex, or Cursor to drive Grok Build? If you already pay for a Grok subscription, this gives any of those agents live X search and data right in their context. A couple of ways to wire it up.
Repo: VasiHemanth/grok-build-plugin