--- name: grok description: > Route a task to the Grok CLI (xAI Grok 4.3) for capabilities Claude lacks or an independent second model: IMAGE generation/editing, VIDEO (image->video), live WEB + X/TWITTER search (real-time data past Claude's cutoff), adversarial second-opinion VERIFICATION. Triggers: ask grok, grok image, generate/make an image, make a video / animate this, grok verify / second opinion, search X / twitter, what's the latest . A capability EXTENSION, not a replacement for Claude's own coding/editing. --- # Grok capability router Claude shells out to the locally-installed **Grok CLI** (`grok.exe`, xAI Grok 4.3) for things Claude can't do natively, or for a genuinely independent second model. Verified working on this machine (2026-06-04): image gen, image->video, live web/X search, text reasoning. **Auth:** Grok uses its own OIDC login (`~/.grok/auth.json`, grok.com, ~6h refresh) — **no API key**. If calls fail with auth errors, the user runs `grok login`. ## The wrapper ``` bash "$CLAUDETOOLS_ROOT/.claude/skills/grok/scripts/ask-grok.sh" ... ``` | Mode | Usage | What it does | |------|-------|--------------| | `text` | `ask-grok.sh text ""` or `text --prompt-file ` | One-shot text answer (independent model). `--prompt-file` for long content (review/summarize a doc). | | `verify` | `ask-grok.sh verify ""` or `verify --prompt-file ` | Adversarial second opinion — Grok tries to REFUTE/find gaps, returns a verdict + reasons. | | `review` | `ask-grok.sh review [""]` | Grok reads the file at `` itself (its `read_file` tool) and reviews it — no embedding, handles large files, can pull in referenced files. Path resolution: absolute, CWD-relative, or relative to `$CLAUDETOOLS_ROOT` — **see the path gotcha below**. Spaces OK. | | `review-files` | `ask-grok.sh review-files [-i ""] [f2 …]` | Review a **set** of files together (grok `read_file`s each) — for cross-file consistency or a multi-file change. Same path resolution as `review` (**see gotcha below**); spaces OK. No code passed as a shell arg → no quote hell. | | `review-diff` | `ask-grok.sh review-diff [-C ] [-i ""] [-- ]` | Review a **git diff** (`git diff ` from ``; default repo root, use `-C` for a submodule e.g. `-C projects/msp-tools/guru-rmm`). The diff goes via the prompt file (not a shell arg); grok can `read_file` changed files for full context (cwd = repo dir). | | `image` | `ask-grok.sh image "" [out.png]` | `image_gen` (Imagine) → copies the artifact to `out` (default `grok-image.png`). | | `video` | `ask-grok.sh video "" [out.mp4]` | `image_to_video` on an input image → copies to `out`. ~60-90s. | | `xsearch` | `ask-grok.sh xsearch ""` | Live web search, returns text with citations. **Grok's multi-agent `web_search` frequently TIMES OUT on multi-part queries**, so xsearch uses `streaming-json` and **auto-falls-back to `gemini search`** when grok doesn't finish (you'll see `[grok xsearch timed out -> answered via gemini search]`). Net: reliable answers; gemini is the workhorse engine. | | `raw` | `ask-grok.sh raw ` | Escape hatch — passes args straight to `grok`. | The script captures JSON (`--output-format json`), parses the result, and for media **retrieves the artifact by sessionId** from `~/.grok/sessions///{images,videos}/` — so artifacts are recovered even when a headless run reports `stopReason: Cancelled` before echoing the path (a known finalization quirk of the `-p` mode). > [!WARNING] > **Path gotcha for `review` / `review-files` (this has bitten us repeatedly).** > A relative path is resolved against ONLY two roots: your **current directory**, > and **`$CLAUDETOOLS_ROOT`** (`/d/claudetools`). It is NOT resolved against a > submodule or any arbitrary subdir. So a path like `server/src/api/auth.rs` that > is relative to a submodule (e.g. `projects/msp-tools/guru-connect/`) fails with > `file not found` whenever your CWD isn't that submodule — even though the file > obviously exists. **When reviewing files in a submodule or any non-root subtree, > pass ABSOLUTE paths** (e.g. build the list with `find "$(pwd)/server/src" -name '*.rs'` > from inside the submodule). Absolute paths always work regardless of CWD and > tolerate spaces. (For `review-diff`, the analogous fix is `-C `.) ## Machine availability (fleet) Grok is **per-machine** — the skill syncs fleet-wide but the binary does not. Availability is gated by `identity.json` (per-machine, gitignored): ```json "grok": { "installed": true, "binary": "C:/Users/guru/.grok/bin/grok.exe", "auth": "oidc", "is_fleet_host": true, "capabilities": ["text","verify","image","video","xsearch"] } ``` - If `grok.installed` is `false` (or the block is absent), `ask-grok.sh` exits **3** with routing guidance instead of failing obscurely. Claude on such a machine should NOT attempt local Grok. - **Fleet Grok hosts: `GURU-5070`, `GURU-BEAST-ROG`** — machines with Grok installed. When others get it, set their `identity.json` `grok` block (and update this line). **Remote routing (NOT yet wired):** a non-host machine cannot run Grok locally. To fulfill a Grok request from elsewhere, route it to the host (`GURU-5070`). Candidate channels: GuruRMM agent command execution (`/rmm` — GURU-5070 is enrolled; the hard part is shipping image/video artifacts back), `grok agent serve` (WebSocket relay), or a coord-API job queue. Until that's built, Grok requests originate on the host machine. ## When to route to Grok - **Image / video creation or editing** — Claude can't generate media; Grok can. (`image`, `video`) - **Current / real-time facts** — anything past Claude's knowledge cutoff, breaking news, latest versions, or X/Twitter sentiment. (`xsearch`) - **Independent verification** — a genuinely different vendor/model to red-team a Claude finding or design before acting on it. (`verify`) - **Diverse drafts / second opinion** — alternative phrasing or approach to compare. (`text`) ## When NOT to - Pure classify/extract/summarize → cheaper via Tier-0 Ollama (`.claude/OLLAMA.md`). - Editing this repo's code → Claude's own agents (the Grok CLI *can* read `.claude/` and run tools, but Claude owns the codebase work). - **Never** delegate unsupervised destructive / production actions to Grok. The earlier SBS post-mortem (`docs/session-notes/2026-06-03-claude-postmortem-grok-mspbackups-sbs.md`) showed Grok over-claims and under-verifies — **always review Grok output before acting on it**, and confirm media is what was asked for (Claude can view images). ## Safety / operational notes - `~/.grok/config.toml` defaults to `permission_mode = "always-approve"` (auto-runs tools). The wrapper's single-context modes (`text`/`verify`/`review*`) override with `--permission-mode dontAsk --no-subagents` (cheap, bounded, timeout-predictable). **`xsearch` is the deliberate exception:** it uses `--yolo` and leaves subagents ENABLED, because `web_search` runs the `grok-4.20-multi-agent` model — passing `--no-subagents` made it hang with zero output (the long-standing xsearch-empty bug; root-caused + fixed 2026-06-16). Don't re-add `--no-subagents` to xsearch. - Prompts are passed via `--prompt-file` only (inline args break on shell quoting). - `grok-build` does NOT support `--effort`/`--reasoning-effort` (`supports_reasoning_effort:false` in the model info) — passing them 400s. Don't. - Models (verify live with `grok models`): `grok-build` ("Grok Build", xAI's latest coding model, 512k ctx — the **documented** default per `docs/user-guide/11-custom-models.md`) and `grok-composer-2.5-fast` ("Cursor's latest coding model", fast). **Gotcha:** on this machine the runtime default that `grok models` reports is `grok-composer-2.5-fast`, and the wrapper pins no `-m`, so it currently rides whatever the runtime default is (not necessarily grok-build). `web_search` uses a SEPARATE model, `grok-4.20-multi-agent` (set via `[tools] web_search` / `GROK_WEB_SEARCH_MODEL`). - After media gen, Claude should **view the image** (Read tool) to confirm correctness; videos can be confirmed by header/ffprobe. ## Reference - Binary: `~/.grok/bin/grok.exe` (not on PATH; the wrapper auto-locates it or honors `GROK=`). - Full capability investigation + verification: see the 2026-06-04 session log. - Grok native tools observed: `image_gen`, `image_edit`, `image_to_video`, `reference_to_video`, `web_search`, `web_fetch`, `x_keyword_search`, `x_semantic_search`, `x_user_search`, `x_thread_fetch`, `run_terminal_command`, file ops, `scheduler_*`, `monitor`, memory.