grok: fix headless reasoning modes — pin grok-4.5 (was stale grok-build)
Grok self-diagnosed and fixed the empty-text failure: the reasoning modes (text/verify/review*) pinned -m grok-build, which the CLI (0.2.111) now rejects as an unknown model id, producing empty output with a blank stopReason. Updated the pin to grok-4.5 (the current default per `grok models`). Media/xsearch keep GROK_MODEL="" (runtime default). Adds HEADLESS.md + PEER_GUIDE.md docs. Verified: `ask-grok.sh text` now returns cleanly on GURU-5070. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
724
.claude/skills/grok/HEADLESS.md
Normal file
724
.claude/skills/grok/HEADLESS.md
Normal file
@@ -0,0 +1,724 @@
|
||||
# Grok headless — exact syntax, abilities, and harness contract
|
||||
|
||||
**Audience:** Claude Code, Gemini/agy, and any automation that shells to Grok.
|
||||
**Scope:** Non-interactive (`-p` / `--prompt-file`) runs only.
|
||||
**Sources of truth:** this file + `scripts/ask-grok.sh` + local
|
||||
`~/.grok/docs/user-guide/14-headless-mode.md` (vendor CLI docs).
|
||||
**Verified on:** GURU-5070 — `grok 0.2.111`, default model `grok-4.5` (2026-07).
|
||||
|
||||
For *when* to call Grok and the peer trust model, see [PEER_GUIDE.md](./PEER_GUIDE.md).
|
||||
For the short skill summary, see [SKILL.md](./SKILL.md).
|
||||
|
||||
---
|
||||
|
||||
## 0. Two layers — do not confuse them
|
||||
|
||||
| Layer | What it is | When to use |
|
||||
|-------|------------|-------------|
|
||||
| **A. Harness wrapper** | `bash .claude/skills/grok/scripts/ask-grok.sh <mode> …` | **Default for Claude/agy.** Modes, timeouts, path conversion, JSON parse, media copy, agy fallback, errorlog. |
|
||||
| **B. Raw Grok CLI** | `grok --prompt-file …` / `grok -p "…"` | Escape hatch via `ask-grok.sh raw …`, debugging, or capabilities the wrapper has no mode for (`image_edit`, `reference_to_video`, resume sessions, tool allowlists). |
|
||||
|
||||
**Rule for peers:** use layer A unless you deliberately need layer B. Do not invent ad-hoc `grok -p` one-liners from memory — quoting, Windows paths, permissions, and artifact recovery will bite you.
|
||||
|
||||
---
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
### Binary location
|
||||
|
||||
| Priority | Source |
|
||||
|----------|--------|
|
||||
| 1 | Env `GROK=` pointing at the executable |
|
||||
| 2 | `.claude/identity.json` → `grok.binary` |
|
||||
| 3 | Auto: `~/.grok/bin/grok.exe`, PATH `grok`, etc. |
|
||||
|
||||
Typical Windows path: `C:\Users\<user>\.grok\bin\grok.exe` (often **not** on PATH).
|
||||
|
||||
```bash
|
||||
# From Git Bash / harness bash:
|
||||
"$HOME/.grok/bin/grok.exe" version
|
||||
# or
|
||||
grok version
|
||||
```
|
||||
|
||||
Example output: `grok 0.2.111 (94172f2aa4) [stable]`
|
||||
|
||||
### Auth (required)
|
||||
|
||||
This fleet uses **OIDC / grok.com login** (no API key in the skill).
|
||||
|
||||
| Method | When |
|
||||
|--------|------|
|
||||
| `grok login` | Interactive machine with browser (normal) |
|
||||
| `grok login --device-auth` | Headless SSH/VM without local browser |
|
||||
| `XAI_API_KEY=…` | CI / container alternative (vendor docs) |
|
||||
|
||||
Credentials cache: `~/.grok/auth.json`. On auth failure: user re-runs login; do not invent keys.
|
||||
|
||||
### Fleet gate (`identity.json`)
|
||||
|
||||
```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`, **`ask-grok.sh` exits 3** immediately with routing guidance. Do not probe further on that machine (remote routing not wired yet).
|
||||
|
||||
### Shell requirements for the wrapper
|
||||
|
||||
- **bash** = Git-for-Windows MSYS bash (not WSL stub). See `windows-bash` skill.
|
||||
- **python** = `py` / `python` / `python3` (JSON field extraction).
|
||||
- **timeout** / **gtimeout** (macOS) for wall-clock limits.
|
||||
- **cygpath** (MSYS) so paths handed to `grok.exe` are native Windows paths.
|
||||
- **Never write prompts to Git-Bash `/tmp` for later Read-tool use** — path mismatch on Windows. Prefer repo-relative `./.claim.md` or the wrapper’s own temp dir.
|
||||
|
||||
---
|
||||
|
||||
## 2. Harness wrapper — exact syntax
|
||||
|
||||
### Invocation skeleton
|
||||
|
||||
```bash
|
||||
# From ClaudeTools repo root (or with CLAUDETOOLS_ROOT set):
|
||||
bash "${CLAUDETOOLS_ROOT:-.}/.claude/skills/grok/scripts/ask-grok.sh" <mode> [args...]
|
||||
```
|
||||
|
||||
Short form when CWD is repo root:
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh <mode> [args...]
|
||||
```
|
||||
|
||||
### Modes (complete)
|
||||
|
||||
| Mode | Syntax | Stdout success | Typical wall time |
|
||||
|------|--------|----------------|-------------------|
|
||||
| `text` | `text "<prompt>"` **or** `text --prompt-file <path>` | Answer text | ≤ ~180s budget |
|
||||
| `verify` | `verify "<claim>"` **or** `verify --prompt-file <path>` | Verdict + reasons | ≤ ~180s |
|
||||
| `review` | `review <file-path> ["instructions"]` | Review text | ≤ ~240s (+ optional embed retry) |
|
||||
| `review-files` | `review-files [-i\|--instr "…"] <f1> [f2 …]` | Review text | ≤ ~300s |
|
||||
| `review-diff` | `review-diff [-C <repo-dir>] [-i "…"] <gitref> [-- <pathspec>]` | Review text | ≤ ~300s |
|
||||
| `image` | `image "<prompt>" [out.png]` | `[ask-grok] image OK -> <out> (session <id>)` | ≤ ~240s |
|
||||
| `video` | `video "<motion>" <input-image> [out.mp4]` | `[ask-grok] video OK -> <out> (session <id>)` | ≤ ~360s |
|
||||
| `xsearch` | `xsearch "<query>"` | Answer text (or agy fallback) | ≤ ~240s then possible agy |
|
||||
| `raw` | `raw <any grok CLI args…>` | Whatever `grok` prints | Unlimited (your problem) |
|
||||
|
||||
Alias: `review` also accepts mode name `file` (same code path).
|
||||
|
||||
### Exit codes (`ask-grok.sh`)
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| `0` | Success — text printed or media copied |
|
||||
| `1` | No usable result / empty artifact / empty git diff |
|
||||
| `2` | Usage error (missing args, file not found for review target, bad mode) |
|
||||
| `3` | Grok not installed on this machine (`identity.json`) |
|
||||
| `127` | Binary or python missing |
|
||||
|
||||
Vendor `grok` itself may exit `0` / `1` / `130` (SIGINT) / `143` (SIGTERM). The wrapper **ignores** grok’s exit for most modes and judges success by JSON `text` or recovered artifact (Cancelled stopReason is common on media).
|
||||
|
||||
### Environment overrides the wrapper honors
|
||||
|
||||
| Env | Effect |
|
||||
|-----|--------|
|
||||
| `GROK=` | Path to `grok` / `grok.exe` |
|
||||
| `GROK_MODEL=` | Model id for modes that pin a model. Default **`grok-4.5`**. Empty string clears pin (used internally for image/video). |
|
||||
| `CLAUDETOOLS_ROOT=` | Repo root for path resolution and errorlog |
|
||||
| `HOME` / user profile | Session artifact search under `~/.grok/sessions/` |
|
||||
|
||||
```bash
|
||||
# Example: force a specific model for verify
|
||||
GROK_MODEL=grok-4.5 bash .claude/skills/grok/scripts/ask-grok.sh verify "Claim: …"
|
||||
```
|
||||
|
||||
### What each mode actually does under the hood
|
||||
|
||||
#### Shared `run_grok` defaults (text / verify / review* / image / video)
|
||||
|
||||
Unless a mode overrides, the wrapper builds:
|
||||
|
||||
```text
|
||||
timeout <secs> <GROK> \
|
||||
--prompt-file <WINPATH(tmp/prompt.txt)> \
|
||||
--output-format json \
|
||||
[-m <GROK_MODEL>] \ # omitted if GROK_MODEL is empty
|
||||
--permission-mode dontAsk \
|
||||
--no-subagents \
|
||||
--no-plan \
|
||||
--cwd <WINPATH(run_cwd)> \
|
||||
[extra mode flags...]
|
||||
```
|
||||
|
||||
- Prompt is **always** a file (never a huge shell-quoted `-p` string).
|
||||
- Paths to grok.exe are **Windows-native** via `cygpath -w` on MSYS.
|
||||
- stdout → temp JSON; stderr → temp err file.
|
||||
- Grok exit code is swallowed (`|| true`); success is content-based.
|
||||
|
||||
#### `text`
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh text "One-sentence question?"
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh text --prompt-file ./.prompt.md
|
||||
```
|
||||
|
||||
- Steers prompt: `Answer directly in text; do not use tools.\n<user content>`
|
||||
- Extra flags: `--disable-web-search --max-turns 3`
|
||||
- Timeout: **180s**
|
||||
- Model: pinned (`GROK_MODEL`, default `grok-4.5`)
|
||||
- cwd: disposable temp work dir
|
||||
- Parses JSON field `text` → prints to stdout
|
||||
|
||||
#### `verify`
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh verify "Claim: the delete API removes the user."
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh verify --prompt-file ./.claim.md
|
||||
```
|
||||
|
||||
- Steers prompt to **adversarially refute** then give verdict + justification; text only, no tools
|
||||
- Same flags/timeout/model as `text`
|
||||
- Note: vendor `--check` / self-verify is **not** used — that verifies Grok’s *own* answer, not an external claim
|
||||
|
||||
#### `review` (single file)
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh review /d/claudetools/path/to/file.rs
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh review ./relative/file.ts "Focus on authz"
|
||||
```
|
||||
|
||||
**Path resolution (strict):**
|
||||
|
||||
1. If `<path>` exists as given (relative to **caller CWD**) → use it
|
||||
2. Else if `$CLAUDETOOLS_ROOT/<path>` exists → use that
|
||||
3. Else → exit 2 `file not found`
|
||||
|
||||
**Not** resolved against arbitrary submodules. For files under
|
||||
`projects/msp-tools/guru-rmm/…` pass **absolute** paths.
|
||||
|
||||
- Instructs Grok to `read_file` the **Windows absolute** path; may read related files; **must not modify**
|
||||
- cwd for grok: **repo root** (`CLAUDETOOLS_ROOT`)
|
||||
- Timeout: **240s**, `--max-turns 12`
|
||||
- If empty result and file ≤ **262144 bytes**: one automatic **embed fallback** (inline file body, no tools, max-turns 3)
|
||||
- If empty and file larger: no embed; fail with session/stopReason
|
||||
|
||||
#### `review-files`
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh review-files \
|
||||
-i "Focus on cross-file auth regressions" \
|
||||
"D:/claudetools/projects/msp-tools/guru-rmm/server/src/a.rs" \
|
||||
"D:/claudetools/projects/msp-tools/guru-rmm/server/src/b.rs"
|
||||
```
|
||||
|
||||
- Flags: `-i` / `--instr` then instruction string; all other args are files
|
||||
- Same path resolution **per file** as `review`
|
||||
- Timeout: **300s**, `--max-turns 24`
|
||||
- Embed fallback if combined size ≤ 256 KiB
|
||||
|
||||
#### `review-diff`
|
||||
|
||||
```bash
|
||||
# Diff against main at monorepo root
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh review-diff main
|
||||
|
||||
# Submodule repo
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh review-diff \
|
||||
-C projects/msp-tools/guru-rmm \
|
||||
-i "Security only" \
|
||||
HEAD~3 -- server/src/
|
||||
|
||||
# Unstaged/staged local changes vs HEAD
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh review-diff HEAD
|
||||
```
|
||||
|
||||
- Runs `git -C <gdir> diff <gitref> [-- pathspec…]` into a temp file
|
||||
- Empty diff → exit 1
|
||||
- Embeds unified diff in the prompt; invites `read_file` on changed paths (relative to `-C` dir; strip `a/` `b/` prefixes)
|
||||
- cwd for grok: **`<gdir>`** (the git root being diffed)
|
||||
- Timeout: **300s**, `--max-turns 20`
|
||||
- Embed fallback: no-tools re-run with diff only if ≤ 256 KiB
|
||||
|
||||
#### `image`
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh image "flat blue shield icon, no text" ./out/icon.png
|
||||
# default out path if omitted:
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh image "a red cube on white"
|
||||
# → copies to ./grok-image.png relative to caller CWD
|
||||
```
|
||||
|
||||
- Prompt forces tool: `image_gen` then stop
|
||||
- **Model pin cleared** (runtime default — media verified on default, not forced coding model)
|
||||
- `--disable-web-search --max-turns 12`, timeout **240s**
|
||||
- Reads JSON `sessionId`; finds newest file under
|
||||
`~/.grok/sessions/*/<sessionId>/images/*`
|
||||
and `cp` to `out`
|
||||
- Success line: `[ask-grok] image OK -> <out> (session <id>)`
|
||||
- Does **not** print the image bytes to stdout
|
||||
|
||||
#### `video`
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh video \
|
||||
"slow push-in, gentle light" \
|
||||
./out/hero.png \
|
||||
./out/hero.mp4
|
||||
```
|
||||
|
||||
- Requires existing input image (exit 2 if missing)
|
||||
- Copies input to temp work dir as **`input.jpg`** (name is fixed for the model prompt)
|
||||
- Prompt forces `image_to_video` on `input.jpg`
|
||||
- Model pin cleared; timeout **360s**; `--max-turns 20`
|
||||
- Artifact from `…/videos/*` → `out` (default `grok-video.mp4`)
|
||||
- Success: `[ask-grok] video OK -> <out> (session <id>)`
|
||||
|
||||
#### `xsearch`
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh xsearch "UniFi OS 4.x latest stable release notes"
|
||||
```
|
||||
|
||||
**Different policy from other modes** (do not “fix” this back to `--no-subagents`):
|
||||
|
||||
```text
|
||||
timeout 240 <GROK> \
|
||||
--prompt-file <prompt> \
|
||||
--output-format streaming-json \
|
||||
--yolo \
|
||||
--no-plan \
|
||||
--cwd <temp> \
|
||||
--max-turns 14
|
||||
```
|
||||
|
||||
- No `--no-subagents` (web_search multi-agent hung with zero output when subagents were disabled — fixed 2026-06-16)
|
||||
- No model pin (searcher model is separate / runtime)
|
||||
- Parses NDJSON lines with `"type":"text"` and concatenates `data`
|
||||
- If exit≠0 or empty: logs error, prints
|
||||
`[grok xsearch timed out -> answered via agy search]`,
|
||||
then **`exec`s** `ask-agy.sh search "<same query>"` when available
|
||||
- **Provenance:** if you see that banner, the answer is **not** pure Grok
|
||||
|
||||
#### `raw`
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh raw \
|
||||
--prompt-file ./p.txt --output-format json --yolo --max-turns 8
|
||||
```
|
||||
|
||||
- Passes all remaining args straight to `"$GROK" "$@"`
|
||||
- **No** timeout, **no** path conversion, **no** JSON parse, **no** media recovery
|
||||
- You own safety. Prefer documented modes.
|
||||
|
||||
---
|
||||
|
||||
## 3. Copy-paste recipes (wrapper)
|
||||
|
||||
```bash
|
||||
ROOT="${CLAUDETOOLS_ROOT:-/d/claudetools}" # adjust; on Windows Git Bash often /d/claudetools
|
||||
AG="$ROOT/.claude/skills/grok/scripts/ask-grok.sh"
|
||||
|
||||
# --- Second opinion ---
|
||||
bash "$AG" verify --prompt-file "$ROOT/.claim.md"
|
||||
|
||||
# --- Text Q&A ---
|
||||
bash "$AG" text "List three risks of disabling MFA for a shared mailbox."
|
||||
|
||||
# --- Single-file review (absolute path) ---
|
||||
bash "$AG" review "D:/claudetools/projects/msp-tools/guru-rmm/server/src/api/auth.rs" \
|
||||
"Security and authz only; cite file:line"
|
||||
|
||||
# --- Multi-file ---
|
||||
bash "$AG" review-files -i "Cross-file consistency" \
|
||||
"D:/claudetools/…/a.rs" "D:/claudetools/…/b.rs"
|
||||
|
||||
# --- Diff in submodule ---
|
||||
bash "$AG" review-diff -C "$ROOT/projects/msp-tools/guru-rmm" HEAD~1
|
||||
|
||||
# --- Still image ---
|
||||
bash "$AG" image "square app icon, blue shield, white check, no text" \
|
||||
"$ROOT/projects/acg-website-showcase/design/icon.png"
|
||||
|
||||
# --- Still then video ---
|
||||
bash "$AG" image "hero still, server rack, soft light, no text, 16:9" /tmp/hero.png
|
||||
bash "$AG" video "slow dolly in" /tmp/hero.png /tmp/hero.mp4
|
||||
# Prefer repo-relative outs on Windows, not Git-Bash /tmp for later tool Read
|
||||
|
||||
# --- Live search ---
|
||||
bash "$AG" xsearch "What is the current xAI Grok CLI default model?"
|
||||
```
|
||||
|
||||
### PowerShell callers
|
||||
|
||||
From PowerShell, still invoke **bash** (MSYS), not `grok.exe` directly, for wrapper modes:
|
||||
|
||||
```powershell
|
||||
bash "D:/claudetools/.claude/skills/grok/scripts/ask-grok.sh" text "ping"
|
||||
```
|
||||
|
||||
Do not nest PowerShell-escaped double quotes into complex `-p` prompts; use `--prompt-file` via the wrapper.
|
||||
|
||||
### Backgrounding
|
||||
|
||||
Run each `ask-grok` as its **own** tool/shell call. Do **not** combine:
|
||||
|
||||
```bash
|
||||
# BAD — empty captures seen fleet-wide
|
||||
bash ask-grok.sh verify "…" & curl …; wait
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Raw Grok CLI headless (layer B)
|
||||
|
||||
Official flag reference: `~/.grok/docs/user-guide/14-headless-mode.md`
|
||||
CLI help: `grok --help` / `grok version` / `grok models`
|
||||
|
||||
### How headless is triggered
|
||||
|
||||
Any of:
|
||||
|
||||
```bash
|
||||
grok -p "prompt text" # --single
|
||||
grok --prompt-file /path/to/prompt.txt
|
||||
grok --prompt-json '<json content blocks>'
|
||||
```
|
||||
|
||||
**Stdin is not the prompt.** Do not pipe the prompt into grok; use `-p` or `--prompt-file`.
|
||||
|
||||
### Output formats
|
||||
|
||||
| Flag | Shape |
|
||||
|------|--------|
|
||||
| (default) `plain` | Human text on stdout |
|
||||
| `--output-format json` | One JSON object after completion |
|
||||
| `--output-format streaming-json` | NDJSON events (`text`, `thought`, `end`, `error`, …) |
|
||||
|
||||
#### JSON success object (fields peers care about)
|
||||
|
||||
```json
|
||||
{
|
||||
"text": "…",
|
||||
"stopReason": "EndTurn",
|
||||
"sessionId": "019f…",
|
||||
"requestId": "…",
|
||||
"thought": "…",
|
||||
"num_turns": 1,
|
||||
"usage": { "input_tokens": 0, "cache_read_input_tokens": 0, "output_tokens": 0, "reasoning_tokens": 0, "total_tokens": 0 },
|
||||
"modelUsage": { "<model-id>": { "inputTokens": 0, "outputTokens": 0, "modelCalls": 1, "costUSD": 0.0 } },
|
||||
"total_cost_usd": 0.0
|
||||
}
|
||||
```
|
||||
|
||||
Error object example:
|
||||
|
||||
```json
|
||||
{"type":"error","message":"Couldn't set model 'grok-build': Invalid params: \"unknown model id\"…"}
|
||||
```
|
||||
|
||||
#### streaming-json events
|
||||
|
||||
| `type` | Meaning |
|
||||
|--------|---------|
|
||||
| `text` | Chunk; field `data` |
|
||||
| `thought` | Reasoning chunk |
|
||||
| `end` | Final; includes `stopReason`, `sessionId`, spend fields |
|
||||
| `error` | Failure |
|
||||
|
||||
Wrapper xsearch concatenates all `type==text` `data` fields.
|
||||
|
||||
### Models (live — re-check with `grok models`)
|
||||
|
||||
```bash
|
||||
grok models
|
||||
```
|
||||
|
||||
**2026-07 snapshot on GURU-5070:**
|
||||
|
||||
- Default: **`grok-4.5`**
|
||||
- Wire/usage name may appear as `grok-4.5-build` inside `modelUsage`
|
||||
- **`grok-build` is invalid** (`unknown model id`) — older docs and an older wrapper default are obsolete
|
||||
- Do **not** pass `--reasoning-effort` / `--effort` unless `grok models` / model menu shows support; unsupported values 400
|
||||
|
||||
Wrapper default for reasoning modes: `GROK_MODEL=grok-4.5` (overridable).
|
||||
|
||||
### Permission modes (headless-critical)
|
||||
|
||||
| Mechanism | Effect |
|
||||
|-----------|--------|
|
||||
| `--yolo` / `--always-approve` / `--permission-mode bypassPermissions` | Auto-approve tool runs (deny rules + hooks still apply) |
|
||||
| `--permission-mode dontAsk` | Passed by wrapper; deny anything not auto-approved / allowed (CI-safe posture) |
|
||||
| Config `~/.grok/config.toml` `[ui] permission_mode = "always-approve"` | Local fleet default can be loose — wrapper flags try to bound peer calls |
|
||||
| Headless + would-prompt | Tool call is **cancelled** and reported to the model (does not hang for UI) |
|
||||
|
||||
**Peers:** for unattended *tool* work you intend (search, media tools), you need either YOLO/bypass or tools that are auto-approved as read-only. The wrapper uses:
|
||||
|
||||
- **dontAsk + no-subagents** for text/verify/review/image/video (prompt steering + media tools)
|
||||
- **yolo + subagents allowed** for xsearch only
|
||||
|
||||
Vendor note: some permission-mode values are better set via Claude-compat `defaultMode` in settings; flag support evolves — if tools silently fail, check stderr with `RUST_LOG=error` and permission docs (`22-permissions-and-safety.md`).
|
||||
|
||||
### Important headless flags (cheat sheet)
|
||||
|
||||
| Flag | Purpose |
|
||||
|------|---------|
|
||||
| `-p` / `--prompt-file` / `--prompt-json` | Enter headless |
|
||||
| `-m` / `--model` | Model id |
|
||||
| `--cwd` | Working directory (project discovery walks up for `.git`) |
|
||||
| `--output-format` | `plain` \| `json` \| `streaming-json` |
|
||||
| `--max-turns N` | Cap agentic loops (headless-only) |
|
||||
| `--no-plan` | Disable plan mode |
|
||||
| `--no-subagents` | Block subagent fan-out |
|
||||
| `--disable-web-search` | Disable web_search + web_fetch |
|
||||
| `--tools a,b,c` | Allowlist built-in tools (headless-only) |
|
||||
| `--disallowed-tools a,b` | Denylist; `Agent` / `Agent(explore)` special forms |
|
||||
| `--allow` / `--deny` | Permission rules `Bash(…)`, `Read(…)`, etc. |
|
||||
| `--rules "…"` | Extra system rules |
|
||||
| `--system-prompt-override` | Replace system prompt |
|
||||
| `--verbatim` | Send prompt exactly |
|
||||
| `--no-memory` | Disable cross-session memory |
|
||||
| `-r` / `--resume ID` | Resume session |
|
||||
| `-c` / `--continue` | Continue latest session in cwd |
|
||||
| `-s` / `--session-id UUID` | **New** session only (must be fresh UUID) |
|
||||
| `--json-schema '…'` | Structured JSON output (implies json format) |
|
||||
| `--sandbox <profile>` | FS/network sandbox |
|
||||
| `--no-auto-update` | Skip update checks |
|
||||
|
||||
### Tool filtering examples (raw)
|
||||
|
||||
```bash
|
||||
# Read-only review style
|
||||
grok --prompt-file ./p.txt --output-format json \
|
||||
--tools "read_file,grep,list_dir" \
|
||||
--permission-mode dontAsk --no-subagents --no-plan --max-turns 12
|
||||
|
||||
# No shell, no edits
|
||||
grok --prompt-file ./p.txt --output-format json --yolo \
|
||||
--disallowed-tools "run_terminal_cmd,search_replace,write" \
|
||||
--max-turns 8
|
||||
```
|
||||
|
||||
Internal shell tool id is `run_terminal_cmd` (not `bash`) per vendor docs.
|
||||
|
||||
### Session resume (raw; wrapper does not multi-turn)
|
||||
|
||||
```bash
|
||||
SID=$(grok --prompt-file ./p1.txt --output-format json --yolo | jq -r .sessionId)
|
||||
grok --prompt-file ./p2.txt --output-format json --yolo --resume "$SID"
|
||||
```
|
||||
|
||||
Each `ask-grok.sh` mode starts a **fresh** session (no `-r`/`-c`).
|
||||
|
||||
### Vendor exit codes
|
||||
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 0 | Completed |
|
||||
| 1 | Error (auth, network, runtime, bad model, …) |
|
||||
| 130 | SIGINT |
|
||||
| 143 | SIGTERM |
|
||||
|
||||
### Env vars affecting headless
|
||||
|
||||
| Variable | Role |
|
||||
|----------|------|
|
||||
| `XAI_API_KEY` | API-key auth |
|
||||
| `GROK_HOME` | Override `~/.grok` |
|
||||
| `GROK_LOG_FILE` | Log path |
|
||||
| `RUST_LOG` | Log level; headless logs on **stderr** (stdout stays clean for json) |
|
||||
| `GROK_DISABLE_AUTOUPDATER=1` | Suppress updates |
|
||||
| `GROK_SANDBOX` | Sandbox profile |
|
||||
|
||||
```bash
|
||||
RUST_LOG=error grok --prompt-file ./p.txt --output-format json --yolo 2>grok.err
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Abilities available headless
|
||||
|
||||
### A. Via wrapper modes (supported peer surface)
|
||||
|
||||
| Ability | Mode | Notes |
|
||||
|---------|------|--------|
|
||||
| One-shot reasoning / drafting | `text` | No tools; web search off |
|
||||
| Adversarial claim check | `verify` | Prompt-steered refute |
|
||||
| Code/doc review (Grok reads files) | `review`, `review-files` | read_file; no modify |
|
||||
| Diff review | `review-diff` | git diff + optional read_file |
|
||||
| Still image generation | `image` | `image_gen` (Imagine) |
|
||||
| Animate one still → short video | `video` | `image_to_video` |
|
||||
| Live web (+ X) search | `xsearch` | May fall back to agy |
|
||||
|
||||
### B. Native Grok tools (exist in product; wrapper coverage)
|
||||
|
||||
| Tool / capability | Wrapper? | How to reach |
|
||||
|-------------------|----------|--------------|
|
||||
| `image_gen` | **Yes** — `image` | Prefer wrapper |
|
||||
| `image_to_video` | **Yes** — `video` | Prefer wrapper |
|
||||
| `image_edit` | **No mode** | Interactive TUI or `raw` + careful prompt + artifact hunt |
|
||||
| `reference_to_video` | **No mode** | Interactive or `raw`; 2–7 refs |
|
||||
| `web_search` / `web_fetch` | **Partial** — `xsearch` | Do not combine with `--no-subagents` |
|
||||
| `x_keyword_search`, `x_semantic_search`, `x_user_search`, `x_thread_fetch` | No dedicated mode | `raw` or interactive; xsearch prompt only asks for `web_search` |
|
||||
| `read_file`, `list_dir`, `grep` | **Yes** in review* | Also available if you `raw` with tools |
|
||||
| `run_terminal_command` / shell | **Not** in safe modes | Only if you `raw --yolo` — **do not** for production MSP actions |
|
||||
| `search_replace` / `write` | **Not** intended for peers | Claude owns repo edits |
|
||||
| MCP tools (e.g. GrepAI) | Depends on config | Project `.grok/config.toml` / user config; headless can use if server up |
|
||||
| Subagents | Off in wrapper except xsearch | `--no-subagents` vs xsearch yolo |
|
||||
| Scheduler / monitor | No | Interactive / specialized |
|
||||
| `/imagine`, `/imagine-video` slash | TUI | Headless uses tools via prompt, not slash UI |
|
||||
|
||||
### C. Media artifact locations
|
||||
|
||||
```text
|
||||
~/.grok/sessions/<encoded-cwd-or-slug>/<sessionId>/images/<file>
|
||||
~/.grok/sessions/<encoded-cwd-or-slug>/<sessionId>/videos/<file>
|
||||
```
|
||||
|
||||
Wrapper: `ls -t ~/.grok/sessions/*/$SID/images/* | head -1` (same for videos).
|
||||
|
||||
Headless may report `stopReason: Cancelled` even when the file exists — **always** recover by sessionId for media, do not trust stdout path alone.
|
||||
|
||||
### D. Explicit non-abilities / anti-patterns headless
|
||||
|
||||
| Do not expect | Why |
|
||||
|---------------|-----|
|
||||
| Long-form multi-scene film | Short clips only |
|
||||
| Print-quality catalog photography | Web/concept grade |
|
||||
| Unsupervised production deletes via Grok | Peer contract + post-mortem |
|
||||
| Stable `grok-build` model id (2026-07) | Unknown model; use `grok-4.5` |
|
||||
| Prompt via stdin pipe | Not supported |
|
||||
| Wrapper multi-turn memory across modes | Fresh session each call |
|
||||
| `ask-grok.sh image_edit` | Does not exist — use raw/interactive |
|
||||
| Mixing background `&` with capture | Empty output friction |
|
||||
|
||||
---
|
||||
|
||||
## 6. Windows / path rules (mandatory)
|
||||
|
||||
1. **`grok.exe` is a native Windows binary.** Git Bash paths like `/d/claudetools/...` or `/tmp/...` often fail inside grok unless converted. The wrapper uses `cygpath -w`.
|
||||
2. **Review targets:** pass absolute Windows or MSYS paths that resolve under CWD or `CLAUDETOOLS_ROOT` only.
|
||||
3. **Submodules:** always absolute paths or `review-diff -C <submodule>`.
|
||||
4. **Spaces in paths:** wrapper handles via prompt file + winpath; avoid embedding paths in fragile double-quoted PowerShell/`curl` chains.
|
||||
5. **Prompt files for peers:** repo-relative `./.claim.md`, not Git-Bash `/tmp`, if a later Claude Read must open them.
|
||||
6. **bash mapping:** harness scripts require MSYS bash — see `windows-bash` skill / CLAUDE.md.
|
||||
|
||||
---
|
||||
|
||||
## 7. Timeouts, turns, and failure modes
|
||||
|
||||
| Mode | timeout(1) secs | max-turns | Empty/fail behavior |
|
||||
|------|-----------------|-----------|---------------------|
|
||||
| text / verify | 180 | 3 | exit 1 + errorlog |
|
||||
| image | 240 | 12 | exit 1 if no artifact |
|
||||
| video | 360 | 20 | exit 1 if no artifact |
|
||||
| review | 240 | 12 | embed retry once ≤256KiB |
|
||||
| review-files | 300 | 24 | embed retry once |
|
||||
| review-diff | 300 | 20 | embed retry once |
|
||||
| xsearch | 240 | 14 | agy search fallback |
|
||||
|
||||
**Functional errors** (empty text, no artifact, xsearch incomplete) call:
|
||||
|
||||
```bash
|
||||
bash "$REPO_ROOT/.claude/scripts/log-skill-error.sh" "grok" "<msg>" --context "…"
|
||||
```
|
||||
|
||||
Soft-fail — does not replace the exit code semantics above.
|
||||
|
||||
### stopReason values
|
||||
|
||||
Peers may see in diagnostics: `EndTurn`, `Cancelled`, empty, etc.
|
||||
`Cancelled` + media: still check session artifact dir.
|
||||
Empty `text` with `EndTurn`: treat as failure / re-prompt.
|
||||
|
||||
---
|
||||
|
||||
## 8. Minimal raw templates (only when wrapper is insufficient)
|
||||
|
||||
### Structured verify-like call (raw mirror of wrapper)
|
||||
|
||||
```bash
|
||||
PF=$(mktemp)
|
||||
printf '%s\n' 'Adversarially evaluate the following claim… Answer in text only; do not use tools. Content:
|
||||
'"$CLAIM" > "$PF"
|
||||
grok --prompt-file "$(cygpath -w "$PF" 2>/dev/null || echo "$PF")" \
|
||||
--output-format json \
|
||||
-m grok-4.5 \
|
||||
--permission-mode dontAsk \
|
||||
--no-subagents \
|
||||
--no-plan \
|
||||
--disable-web-search \
|
||||
--max-turns 3 \
|
||||
--cwd "$(cygpath -w "$PWD" 2>/dev/null || echo "$PWD")"
|
||||
```
|
||||
|
||||
Prefer `ask-grok.sh verify` instead.
|
||||
|
||||
### image_edit sketch (unsupported by wrapper — fragile)
|
||||
|
||||
```bash
|
||||
# Interactive preferred. Raw sketch only:
|
||||
# 1) Put source image in --cwd
|
||||
# 2) Prompt: use image_edit on ./source.png with description …
|
||||
# 3) --output-format json --yolo --max-turns 12
|
||||
# 4) Recover from ~/.grok/sessions/**/<sessionId>/images/
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh raw \
|
||||
--prompt-file ./edit-prompt.txt \
|
||||
--output-format json --yolo --no-plan --max-turns 12 \
|
||||
--cwd "D:/path/with/source"
|
||||
```
|
||||
|
||||
### Live model id check (run before debugging “unknown model”)
|
||||
|
||||
```bash
|
||||
grok models
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Security posture for headless peers
|
||||
|
||||
1. Prefer wrapper modes that disable web search and subagents for pure reasoning.
|
||||
2. Never `raw --yolo` against production MSP APIs or vault paths as a substitute for Claude skills.
|
||||
3. Review prompts always say **do not modify**; still treat Grok as untrusted for writes.
|
||||
4. Media: view/inspect before client or public use ([PEER_GUIDE.md](./PEER_GUIDE.md) §3).
|
||||
5. xsearch: disclose agy fallback when the banner appears.
|
||||
6. Secrets: never put decrypted credentials in prompts or generated images.
|
||||
|
||||
---
|
||||
|
||||
## 10. Quick reference card
|
||||
|
||||
```text
|
||||
WRAPPER:
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh text|verify|review|review-files|review-diff|image|video|xsearch|raw …
|
||||
|
||||
EXITS: 0 ok | 1 no result | 2 usage | 3 not installed | 127 missing binary/python
|
||||
|
||||
DEFAULT MODEL (reasoning modes): grok-4.5 (override GROK_MODEL=)
|
||||
MEDIA / XSEARCH MODEL: runtime default (pin cleared)
|
||||
|
||||
AUTH: grok login | identity.json grok.installed
|
||||
DOCS: ~/.grok/docs/user-guide/14-headless-mode.md
|
||||
PEER: .claude/skills/grok/PEER_GUIDE.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Related paths
|
||||
|
||||
| Path | Role |
|
||||
|------|------|
|
||||
| `scripts/ask-grok.sh` | Implementation (read when behavior is ambiguous) |
|
||||
| [SKILL.md](./SKILL.md) | Skill entry + short mode table |
|
||||
| [PEER_GUIDE.md](./PEER_GUIDE.md) | When/why + media product rules + trust |
|
||||
| `~/.grok/docs/user-guide/14-headless-mode.md` | Vendor headless reference |
|
||||
| `~/.grok/docs/user-guide/22-permissions-and-safety.md` | Permission pipeline |
|
||||
| `docs/session-notes/2026-06-03-claude-postmortem-grok-mspbackups-sbs.md` | Why peers must verify end-state |
|
||||
|
||||
---
|
||||
|
||||
*Last verified against live CLI on GURU-5070: grok 0.2.111, models default `grok-4.5`, `grok-build` rejected. Re-run `grok models` after CLI upgrades.*
|
||||
437
.claude/skills/grok/PEER_GUIDE.md
Normal file
437
.claude/skills/grok/PEER_GUIDE.md
Normal file
@@ -0,0 +1,437 @@
|
||||
# How Claude and Gemini (agy) should interact with Grok
|
||||
|
||||
**Audience:** Claude Code sessions and Antigravity/Gemini (`agy`) sessions in the
|
||||
ClaudeTools harness. **Author:** Grok (xAI). **Status:** live peer contract.
|
||||
|
||||
This is the canonical brief for *calling* Grok as a peer (judgment + trust).
|
||||
|
||||
| Doc | Use for |
|
||||
|-----|---------|
|
||||
| **[HEADLESS.md](./HEADLESS.md)** | **Exact headless syntax**, every `ask-grok.sh` mode, flags, timeouts, exit codes, raw CLI, abilities matrix, Windows paths |
|
||||
| [SKILL.md](./SKILL.md) | Short skill entry + mode table |
|
||||
| `scripts/ask-grok.sh` | Implementation source of truth if docs lag |
|
||||
|
||||
Read **this** file for *when*, *how hard*, and *what to trust*.
|
||||
|
||||
---
|
||||
|
||||
## 1. Who Grok is in this harness
|
||||
|
||||
| Fact | Detail |
|
||||
|------|--------|
|
||||
| Vendor / product | xAI **Grok** via the local **Grok CLI** (`grok.exe`), OIDC login (no API key) |
|
||||
| Primary role | **Independent second model** + capabilities Claude/agy lack (image/video gen, X search) |
|
||||
| Not the owner | **Claude owns codebase work** (edits, commits, production mutations, skill execution). Grok is fresh, skeptical eyes — not the operator of record. |
|
||||
| Sibling peer | **agy** (Gemini via Antigravity CLI) is the other second-opinion router. Same *intent* (verify/review/text); different strengths. |
|
||||
| Fleet hosts | Gated by `.claude/identity.json` → `grok.installed`. Today: **GURU-5070**, **GURU-BEAST-ROG**. Exit code **3** if not installed. |
|
||||
|
||||
Two invocation shapes:
|
||||
|
||||
1. **Headless peer call** (normal for Claude/agy) — `ask-grok.sh <mode> …`
|
||||
2. **Interactive Grok TUI** (user opens Grok as the driver) — Grok loads
|
||||
`CLAUDE.md` + `AGENTS.md` + `.grok/` coexistence. Still not a free hand on
|
||||
production; same safety bar.
|
||||
|
||||
---
|
||||
|
||||
## 2. How to call Grok (always use the skill wrapper)
|
||||
|
||||
```bash
|
||||
bash "$CLAUDETOOLS_ROOT/.claude/skills/grok/scripts/ask-grok.sh" <mode> ...
|
||||
```
|
||||
|
||||
| Mode | Use when | Notes |
|
||||
|------|----------|-------|
|
||||
| `text` | One-shot answer, alternate draft, design critique | `--prompt-file` for long content |
|
||||
| `verify` | Adversarial check of a claim/finding/plan | Grok is steered to **refute** first |
|
||||
| `review` | Independent review of **one** file | Grok `read_file`s it; pass **absolute** paths for submodule files |
|
||||
| `review-files` | Cross-file review of a change set | Same path rule; optional `-i "instructions"` |
|
||||
| `review-diff` | Review a git range | `-C <submodule>` when the repo isn't the monorepo root |
|
||||
| `image` | Generate a still image from text | Imagine `image_gen` → copies PNG/JPG to `out` |
|
||||
| `video` | Animate an **existing** still into a short clip | `image_to_video`; needs input image; ~60–90s |
|
||||
| `xsearch` | Live web + X facts past cutoff | May auto-fall back to **agy search** on timeout |
|
||||
| `raw` | Escape hatch only | You own the flags and safety |
|
||||
|
||||
**Exact syntax, flags, timeouts, exit codes, embed fallbacks, raw CLI, and the
|
||||
full abilities matrix:** **[HEADLESS.md](./HEADLESS.md)** (authoritative).
|
||||
|
||||
Do **not** hand-roll `grok -p …` from memory. The wrapper handles prompt files,
|
||||
Windows path conversion, timeouts, JSON parse, media artifact recovery, model
|
||||
pinning (`grok-4.5` for reasoning modes as of 2026-07), and errorlog.
|
||||
|
||||
**agy callers:** same wrapper. You do not need a separate Gemini→Grok bridge.
|
||||
If you are Gemini/agy and need Grok's unique lanes (**media generation**, X
|
||||
search, or a third vendor after Claude already reviewed), shell the same
|
||||
`ask-grok.sh`.
|
||||
|
||||
Media is a first-class reason to call Grok — see **§3 Media generation** below.
|
||||
|
||||
---
|
||||
|
||||
## 3. Media generation (pictures, video, edits) — Grok-only lane
|
||||
|
||||
Claude and agy **cannot generate** images or video. Grok can. Treat media as a
|
||||
primary peer capability, not a side note.
|
||||
|
||||
### Capability map
|
||||
|
||||
| Need | Who / how | Notes |
|
||||
|------|-----------|--------|
|
||||
| **New still image** from text | Grok `ask-grok.sh image "<prompt>" [out.png]` | Native tool: `image_gen` (Imagine). Default out: `grok-image.png`. |
|
||||
| **Edit / transform** an existing image (style transfer, object change, keep likeness) | Grok native `image_edit` | **No dedicated wrapper mode yet.** Use interactive Grok, or `raw` / a careful prompt that forces `image_edit` with a path the session can read. Prefer interactive when quality matters. |
|
||||
| **Animate one still** → short video | Grok `ask-grok.sh video "<motion>" <input-image> [out.mp4]` | Native tool: `image_to_video`. Input must exist on disk. ~60–90s. Default out: `grok-video.mp4`. |
|
||||
| **Video from multiple reference images** + prompt | Grok native `reference_to_video` | **No dedicated wrapper mode yet.** Interactive or `raw`. Needs 2–7 reference images. |
|
||||
| **Describe / QA an existing image** (no new pixels) | **agy** `image-analyze` | Vision only. Do **not** call Grok for "what is in this screenshot?" unless Grok is already interactive. |
|
||||
| Icons, mockups, marketing art, UI concepts, client-facing graphics | Grok `image` | Claude owns placement into the repo/site after visual check. |
|
||||
|
||||
**Summary:** generate/edit/animate → **Grok**. Look-at / describe → **agy**
|
||||
(or Claude's own vision if available). Never invent media with Ollama.
|
||||
|
||||
### How the wrapper delivers artifacts
|
||||
|
||||
1. Headless Grok runs Imagine / video tools.
|
||||
2. Artifacts land under `~/.grok/sessions/<…>/<sessionId>/{images,videos}/`.
|
||||
3. `ask-grok.sh` recovers by `sessionId` and **copies** to the path you passed
|
||||
(even when headless reports a flaky `stopReason: Cancelled` — known quirk).
|
||||
4. Stdout looks like: `[ask-grok] image OK -> ./out/icon.png (session …)`.
|
||||
|
||||
If exit code is non-zero or the out file is missing/empty, do not invent a
|
||||
placeholder image — retry once or escalate to the user.
|
||||
|
||||
### Prompt craft for media
|
||||
|
||||
**Stills (`image`) — be specific:**
|
||||
|
||||
```
|
||||
Subject + composition + style + constraints.
|
||||
Example: "Flat vector app icon, blue shield with white checkmark, centered,
|
||||
solid dark navy background, no text, no watermark, square, high contrast"
|
||||
```
|
||||
|
||||
Useful knobs to put in the prompt (Imagine respects natural language, not a
|
||||
separate style API via the wrapper):
|
||||
|
||||
- Aspect / framing: square icon, wide banner, portrait poster, UI mockup 16:9
|
||||
- Style: flat vector, photoreal, isometric, wireframe, screenshot-like
|
||||
- Negative constraints: "no text", "no watermark", "no extra limbs", "single object"
|
||||
- Brand: only when the user supplied colors/logo rules — do not invent ACG branding
|
||||
|
||||
**Video (`video`) — motion prompt + still:**
|
||||
|
||||
```
|
||||
Motion only (camera + subject action). The still already defines appearance.
|
||||
Example: "Slow push-in, gentle parallax, subtle light flicker, no morphing faces"
|
||||
```
|
||||
|
||||
- Always pass a real input path: `video "<motion>" ./assets/hero.png ./out/hero.mp4`
|
||||
- Generate the still first (`image`) if you do not already have one
|
||||
- Keep motion simple; complex multi-scene stories fail more often than a short loop
|
||||
|
||||
**Edits / multi-ref video (no wrapper mode):**
|
||||
|
||||
- Interactive Grok session is the reliable path for `image_edit` and
|
||||
`reference_to_video`.
|
||||
- If you must stay headless, use `raw` only with a human-approved prompt; recover
|
||||
artifacts from the session dir the same way the wrapper does.
|
||||
|
||||
### Post-generation checklist (mandatory for peers)
|
||||
|
||||
1. Confirm the output file exists and size > 0.
|
||||
2. **Images:** Claude (or agy vision) **opens/views** the file — does it match the
|
||||
brief? Wrong subject, text garbage, off-brand, NSFW/odd artifacts → regenerate
|
||||
with a tighter prompt; do not ship.
|
||||
3. **Video:** confirm container (ffprobe/header); spot-check if a player is
|
||||
available. Duration is short (tool defaults ~6–10s class); do not promise
|
||||
long-form film.
|
||||
4. Place final assets under the **project path the user expects** (not only
|
||||
`~/.grok/sessions/…`). The wrapper copy path is the handoff.
|
||||
5. Client-facing or public site: human glance before publish when stakes are real.
|
||||
|
||||
### Media recipes
|
||||
|
||||
```bash
|
||||
# Still → project path
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh image \
|
||||
"flat blue shield icon, white check, no text, square" \
|
||||
./projects/acg-website-showcase/design/icon-shield.png
|
||||
|
||||
# Still then animate
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh image \
|
||||
"hero still, modern server room, soft light, no text, 16:9" \
|
||||
./tmp-hero.png
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh video \
|
||||
"slow dolly forward, subtle dust motes, cinematic" \
|
||||
./tmp-hero.png \
|
||||
./out/hero-loop.mp4
|
||||
```
|
||||
|
||||
Then **view** `./projects/.../icon-shield.png` (and inspect the mp4) before any
|
||||
commit, Discord post, or client send.
|
||||
|
||||
### What not to do with media
|
||||
|
||||
- Do not use agy/Claude "generate an image" paths — they do not own Imagine.
|
||||
- Do not skip visual QA and paste a path into a ticket/site blindly.
|
||||
- Do not put secrets, real customer PII, or internal credentials into image
|
||||
prompts or burned-in text on graphics.
|
||||
- Do not expect print-resolution catalogs or long-form video from these tools;
|
||||
they are short-form / concept / web-asset grade unless proven otherwise.
|
||||
|
||||
---
|
||||
|
||||
## 4. When to route to Grok vs agy vs neither
|
||||
|
||||
### Prefer Grok
|
||||
|
||||
- **Any new pixels:** stills, edits, animate-from-still, multi-ref video
|
||||
(`image` / `video` / native edit tools) — **Grok-only**
|
||||
- X/Twitter-native search or social sentiment (`xsearch`)
|
||||
- You already used **agy** and want a **different vendor** to triangulate
|
||||
- User said "ask Grok" / "grok image" / "make a video" / "grok verify"
|
||||
|
||||
### Prefer agy (Gemini)
|
||||
|
||||
- Vision **analysis** of an existing image (`image-analyze`) — report only, no generation
|
||||
- Live web search when you want Gemini's search path (`search`)
|
||||
- You already used **Grok** and want a different vendor
|
||||
- User said "ask Gemini" / "agy verify"
|
||||
|
||||
### Prefer neither (cheaper / local)
|
||||
|
||||
- Classify / extract / short summarize → **Tier-0 Ollama** (`.claude/OLLAMA.md`)
|
||||
- Routine code edits and harness skill work → **Claude** (owner)
|
||||
|
||||
### Triangulate (high stakes)
|
||||
|
||||
For security, auth, credentials, migrations, production risk, or "are we about
|
||||
to do something irreversible?":
|
||||
|
||||
1. Claude states the claim with evidence (files, commands, expected state).
|
||||
2. `ask-grok.sh verify` **and/or** `ask-agy.sh verify` on the same claim.
|
||||
3. **Disagreement is a stop signal** — do not average away conflict; investigate.
|
||||
4. Human gate before any write that leaves the machine.
|
||||
|
||||
---
|
||||
|
||||
## 5. How to brief Grok (prompt craft)
|
||||
|
||||
Grok is strongest when the prompt is **concrete, bounded, and adversarial**.
|
||||
Weak when given vague "look over this" or trusted to complete multi-step
|
||||
production mutations unsupervised.
|
||||
|
||||
### Good `verify` brief
|
||||
|
||||
```
|
||||
Claim: [one sentence]
|
||||
|
||||
Evidence Claude already has:
|
||||
- file:line or command output (paste or path)
|
||||
- expected end-state if this is true
|
||||
|
||||
Constraints:
|
||||
- Try to REFUTE the claim first
|
||||
- Verdict first: CONFIRMED | PARTIAL | REFUTED | INCONCLUSIVE
|
||||
- Confidence 0-100
|
||||
- Cite file:line or missing evidence
|
||||
- No code edits, no production commands
|
||||
```
|
||||
|
||||
### Good `review` / `review-files` brief
|
||||
|
||||
```
|
||||
Scope: [what changed and why]
|
||||
Focus: [bugs / security / API contract / missed edge cases]
|
||||
Ignore: style nits unless they hide bugs
|
||||
Output: findings ranked by severity with file:line; end with residual risks
|
||||
Do not modify files.
|
||||
```
|
||||
|
||||
### Good `text` brief
|
||||
|
||||
- One clear question or deliverable.
|
||||
- Any hard constraints (tone, length, audience, "no emojis", ASCII markers).
|
||||
- Context that is **not** already in a path Grok will read — or pass the path
|
||||
via `review` / `--prompt-file` instead of pasting a novel.
|
||||
|
||||
### Bad briefs (avoid)
|
||||
|
||||
- "Make sure everything is fine" with no claim or files
|
||||
- Dumping an entire monorepo into the prompt
|
||||
- Asking Grok to "go fix production" or run MSP vendor APIs unsupervised
|
||||
- Relative paths into a **submodule** without absolute resolution (see SKILL.md
|
||||
path gotcha — this has failed repeatedly)
|
||||
|
||||
### Long content
|
||||
|
||||
Use `text --prompt-file path` or `verify --prompt-file path`. Never shove large
|
||||
blobs through shell quoting. On Windows PowerShell, prefer the wrapper + prompt
|
||||
file; do not embed nested double-quotes in `curl`/plink-style invocations.
|
||||
|
||||
---
|
||||
|
||||
## 6. What Grok will return (and how you should treat it)
|
||||
|
||||
### Headless modes
|
||||
|
||||
- **Stdout:** the answer text (or a path line for media).
|
||||
- **stderr / prefixes:** diagnostics like
|
||||
`[grok xsearch timed out -> answered via agy search]` — surface these to the user
|
||||
when they change provenance.
|
||||
- **Exit codes:** `0` ok · `1` no result · `2` usage · `3` not installed on this
|
||||
machine · `127` binary missing.
|
||||
|
||||
### Expected tone from Grok
|
||||
|
||||
When steered as a reviewer (and when `AGENTS.md` applies), Grok aims for:
|
||||
|
||||
- No emojis; ASCII markers `[OK]` `[WARN]` `[ERROR]` `[INFO]`
|
||||
- Verdict **first**, then reasoning
|
||||
- Active refutation on verify
|
||||
- `file:line` on code review
|
||||
- Explicit **confidence**
|
||||
|
||||
If a headless call returns soft prose without a verdict, **re-prompt** with the
|
||||
verify template above, or treat the answer as draft-quality only.
|
||||
|
||||
### Trust model (non-negotiable)
|
||||
|
||||
From the 2026-06-03 mspbackups post-mortem and standing harness rules:
|
||||
|
||||
1. **Never act on Grok output without review** when the next step is a write,
|
||||
production call, billing, credential, or client-facing message.
|
||||
2. **HTTP 200 ≠ done.** Grok (and any model) can over-claim. Require
|
||||
read-back of end-state for mutations — Claude owns that loop.
|
||||
3. **Media:** Claude must open/view generated images (and check video files);
|
||||
do not ship uninspected art. See §3.
|
||||
4. **xsearch provenance:** if the wrapper fell back to agy, say so — it is no
|
||||
longer a pure xAI answer.
|
||||
5. Grok can **over-claim and under-verify**. That is why you call it for
|
||||
*critique*, not for *authority* (media is different: Grok *is* the generator,
|
||||
but peers still QA the artifact).
|
||||
|
||||
---
|
||||
|
||||
## 7. What Grok must not be asked to own
|
||||
|
||||
| Task | Who owns it |
|
||||
|------|-------------|
|
||||
| Edit / commit / push this repo | Claude |
|
||||
| Syncro, vault, RMM, Graph, UniFi, MSP360, etc. | Claude via **skills** (skill-first; never hand-roll) |
|
||||
| Unsupervised production deletes / disables / purges | Human + Claude with confirm gates |
|
||||
| Final "done" declaration on client work | Claude after check-skills |
|
||||
| Cheap classify/summarize | Ollama Tier-0 |
|
||||
|
||||
Grok *can* run tools in interactive or poorly constrained headless runs
|
||||
(`permission_mode` defaults elsewhere can be loose). The wrapper deliberately
|
||||
uses `dontAsk` + `--no-subagents` for text/verify/review so peer calls stay
|
||||
bounded. **Do not** expand peer calls into multi-step agentic production work
|
||||
via `raw` unless a human is driving and watching.
|
||||
|
||||
---
|
||||
|
||||
## 8. Operational gotchas (peer callers)
|
||||
|
||||
| Gotcha | What to do |
|
||||
|--------|------------|
|
||||
| Submodule relative paths in `review*` | Pass **absolute** paths; for diffs use `-C projects/...` |
|
||||
| Grok not installed here | Exit 3 — do not invent a local binary; note host routing gap |
|
||||
| Auth errors | User runs `grok login` (OIDC, ~hours-scale refresh) |
|
||||
| xsearch timeout | Accept agy fallback answer; label provenance |
|
||||
| Empty review result | Wrapper may embed-fallback once if file < ~256KB; if still empty, try `text --prompt-file` with a bounded excerpt |
|
||||
| Backgrounding | Do **not** mix `ask-grok` with `&` + foreground probes in one shell; separate tool calls (see errorlog friction) |
|
||||
| Model pin | Reasoning modes pin **`grok-4.5`** via wrapper (`GROK_MODEL=` override). **`grok-build` is invalid** on current CLI. Media/xsearch clear the pin |
|
||||
| Do not pass `--effort` unless model advertises it | Unsupported effort levels error |
|
||||
| Media missing after "OK-ish" run | Check `~/.grok/sessions/**/images` or `videos`; wrapper should have copied — if not, retry `image`/`video` once |
|
||||
| `image_edit` / `reference_to_video` | No `ask-grok.sh` mode yet — interactive Grok or careful `raw` |
|
||||
|
||||
---
|
||||
|
||||
## 9. How Grok thinks about *you* (Claude / Gemini)
|
||||
|
||||
When Grok is asked for a second opinion, assume:
|
||||
|
||||
- **Claude** already explored the repo, ran skills, and holds the operational
|
||||
plan. Grok's job is to stress-test claims and surface holes — not to re-derive
|
||||
the entire harness from zero unless the prompt is a cold one-shot.
|
||||
- **agy** is a peer, not a subordinate. Dual-model disagreement is valuable data.
|
||||
- Prefer **short, decisive** feedback Claude can act on. Long essays without a
|
||||
verdict waste the call.
|
||||
- If evidence is missing, say **INCONCLUSIVE** and list what would change the
|
||||
verdict — do not invent confirmation.
|
||||
|
||||
---
|
||||
|
||||
## 10. Minimal recipes
|
||||
|
||||
### Claude: adversarial verify before a risky step
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh verify --prompt-file ./.claim.md
|
||||
```
|
||||
|
||||
Put the claim + evidence in `./.claim.md` (repo-relative; avoid `/tmp` on Windows).
|
||||
|
||||
### Claude: review a multi-file patch in a submodule
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh review-files -i "Focus on authz regressions" \
|
||||
"$(pwd)/server/src/api/auth.rs" \
|
||||
"$(pwd)/server/src/api/session.rs"
|
||||
```
|
||||
|
||||
### Claude / agy: generate then inspect an image
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh image \
|
||||
"flat icon, blue shield, no text" ./out/icon.png
|
||||
# then Read/view ./out/icon.png before using it
|
||||
```
|
||||
|
||||
### Claude / agy: still → short video
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh image \
|
||||
"product hero, clean desk, soft light, no text, 16:9" ./out/hero.png
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh video \
|
||||
"slow push-in, gentle light shift" ./out/hero.png ./out/hero.mp4
|
||||
```
|
||||
|
||||
### agy session: need Grok media or a third-vendor check
|
||||
|
||||
Same `ask-grok.sh image` / `video` / `verify` commands. For pure second opinion
|
||||
without media, either `ask-grok.sh verify` or stay on `ask-agy.sh verify` —
|
||||
pick **one** unless stakes justify both. For "what is in this PNG?", use
|
||||
`ask-agy.sh image-analyze`, not Grok gen.
|
||||
|
||||
### Triangulate high-stakes claim
|
||||
|
||||
```bash
|
||||
bash .claude/skills/grok/scripts/ask-grok.sh verify --prompt-file ./.claim.md
|
||||
bash .claude/skills/agy/scripts/ask-agy.sh verify --prompt-file ./.claim.md
|
||||
# Compare; on disagreement, stop and investigate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Related paths
|
||||
|
||||
| Path | Role |
|
||||
|------|------|
|
||||
| **[HEADLESS.md](./HEADLESS.md)** | **Exact headless syntax + abilities** |
|
||||
| [SKILL.md](./SKILL.md) | Modes, flags, fleet install, safety summary |
|
||||
| `scripts/ask-grok.sh` | Implementation |
|
||||
| [../agy/SKILL.md](../agy/SKILL.md) | Sibling second-opinion router |
|
||||
| `AGENTS.md` (repo root) | What **interactive/reviewer Grok** is told about its own role |
|
||||
| `GEMINI.md` (repo root) | Parallel reviewer brief for Gemini/agy |
|
||||
| `.grok/README.md` | When Grok *drives* the harness (hooks, skills mirrors) |
|
||||
| `docs/session-notes/2026-06-03-claude-postmortem-grok-mspbackups-sbs.md` | False-completion case study — required reading for trust model |
|
||||
| `.claude/SKILL_ROUTING.md` | Request → skill map (`grok` / `agy` rows) |
|
||||
|
||||
---
|
||||
|
||||
## 12. One-line contract
|
||||
|
||||
**Call Grok for independent critique, live/X search, and all picture/video
|
||||
generation; never for unsupervised ownership of ClaudeTools production work.
|
||||
Brief tightly; for verify demand a verdict; for media QA the artifact; treat
|
||||
disagreement with agy as a stop.**
|
||||
@@ -10,6 +10,14 @@ 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.
|
||||
|
||||
> **Peer contract (Claude + Gemini/agy):**
|
||||
> - [PEER_GUIDE.md](./PEER_GUIDE.md) — when to call Grok, media product rules, trust model
|
||||
> - [HEADLESS.md](./HEADLESS.md) — **exact headless syntax**, every wrapper mode,
|
||||
> flags, timeouts, exit codes, raw CLI, abilities matrix, Windows paths
|
||||
>
|
||||
> Short mode table stays below; if syntax conflicts, **HEADLESS.md + `ask-grok.sh`
|
||||
> win**.
|
||||
|
||||
**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`.
|
||||
|
||||
@@ -85,10 +93,12 @@ Grok is **per-machine** — the skill syncs fleet-wide but the binary does not.
|
||||
- `~/.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`).
|
||||
- Models (verify live with `grok models`): **2026-07 fleet host reports default `grok-4.5`** (usage may show `grok-4.5-build`). The wrapper pins **`-m grok-4.5`** for text/verify/review* (`GROK_MODEL` override). **`grok-build` is no longer a valid model id** (unknown model error). Image/video/xsearch clear the pin and use the runtime default. Do not pass `--effort` unless the live model advertises support.
|
||||
- After media gen, Claude should **view the image** (Read tool) to confirm correctness; videos can be confirmed by header/ffprobe.
|
||||
- **Full headless reference:** [HEADLESS.md](./HEADLESS.md).
|
||||
|
||||
## 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.
|
||||
- Headless syntax + abilities: [HEADLESS.md](./HEADLESS.md). Peer judgment: [PEER_GUIDE.md](./PEER_GUIDE.md).
|
||||
- Vendor docs on machine: `~/.grok/docs/user-guide/14-headless-mode.md`.
|
||||
- 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.
|
||||
|
||||
@@ -101,12 +101,13 @@ fi
|
||||
# --no-subagents made it hang with zero output (root cause, 2026-06-16). See xsearch.
|
||||
GROK_PERM_FLAGS=(--permission-mode dontAsk)
|
||||
GROK_SUBAGENT_FLAGS=(--no-subagents)
|
||||
# Pin xAI's flagship grok-build for the reasoning modes (text/verify/review*) so the
|
||||
# second-opinion quality is deterministic and not at the mercy of the runtime default
|
||||
# (which drifts -- this machine's `grok models` reports grok-composer-2.5-fast, a fast
|
||||
# Cursor coding model). xsearch + image/video clear this to "" to use the runtime
|
||||
# default (xsearch's searcher is a separate model; media gen was verified on default).
|
||||
GROK_MODEL="${GROK_MODEL:-grok-build}"
|
||||
# Pin a known-good coding/reasoning model for text/verify/review* so second-opinion
|
||||
# quality is deterministic. Live default drifts (2026-07: `grok models` reports
|
||||
# grok-4.5; older docs said grok-build / grok-composer-2.5-fast — grok-build is now
|
||||
# rejected as unknown model id). Override with GROK_MODEL= if needed.
|
||||
# xsearch + image/video clear this to "" to use the runtime default (xsearch's
|
||||
# searcher is a separate multi-agent path; media gen verified on default).
|
||||
GROK_MODEL="${GROK_MODEL:-grok-4.5}"
|
||||
|
||||
run_grok() {
|
||||
local to="$1"; shift
|
||||
|
||||
Reference in New Issue
Block a user