90 lines
6.0 KiB
Markdown
90 lines
6.0 KiB
Markdown
---
|
|
name: grok
|
|
description: >
|
|
Route a task to the Grok CLI (xAI Grok 4.3) for capabilities Claude lacks or
|
|
for an independent second model. Use for: IMAGE generation/editing, VIDEO
|
|
generation (image->video), live WEB + X/TWITTER search (current/real-time
|
|
data past Claude's cutoff), and adversarial second-opinion VERIFICATION or
|
|
drafts. Invoke on: "ask grok", "grok image", "generate/make an image",
|
|
"make a video / animate this", "grok verify / second opinion from grok",
|
|
"search X / twitter", "what's the latest <current-event/version>". Grok is a
|
|
capability EXTENSION (image/video/live-data), 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> ...
|
|
```
|
|
|
|
| Mode | Usage | What it does |
|
|
|------|-------|--------------|
|
|
| `text` | `ask-grok.sh text "<prompt>"` or `text --prompt-file <path>` | One-shot text answer (independent model). `--prompt-file` for long content (review/summarize a doc). |
|
|
| `verify` | `ask-grok.sh verify "<claim/finding>"` or `verify --prompt-file <path>` | Adversarial second opinion — Grok tries to REFUTE/find gaps, returns a verdict + reasons. |
|
|
| `review` | `ask-grok.sh review <file-path> ["<instructions>"]` | Grok reads the file at `<path>` itself (its `read_file` tool, run in the repo) and reviews it — no embedding, handles large files, can pull in referenced files. |
|
|
| `image` | `ask-grok.sh image "<prompt>" [out.png]` | `image_gen` (Imagine) → copies the artifact to `out` (default `grok-image.png`). |
|
|
| `video` | `ask-grok.sh video "<motion prompt>" <input-image> [out.mp4]` | `image_to_video` on an input image → copies to `out`. ~60-90s. |
|
|
| `xsearch` | `ask-grok.sh xsearch "<query>"` | Live `web_search` + X/Twitter tools; returns text with citations. |
|
|
| `raw` | `ask-grok.sh raw <grok args...>` | 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/<enc-cwd>/<sessionId>/{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).
|
|
|
|
## 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.
|
|
- **Current fleet Grok host: `GURU-5070`** — the only machine with Grok installed right now. 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 overrides with `--permission-mode dontAsk` and `--no-subagents`; do not bypass that.
|
|
- Prompts are passed via `--prompt-file` only (inline args break on shell quoting).
|
|
- `grok-build` rejects `--effort`/`--reasoning-effort` (400) — don't pass them.
|
|
- Models available: `grok-build` (default), `grok-composer-2.5-fast`. The agent self-reports as Grok 4.3.
|
|
- 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.
|