use-grok

name	use-grok
display_name	Use Grok
description	Spawn xAI Grok CLI subagents from bash to offload coding/implementation work from the parent Claude. Use when the user says "use grok", "build with grok", "ask grok", "grok -p", "get a grok second opinion", or asks to delegate work to Grok. Grok's work MUST be independently verified by the parent — it exits 0 and narrates success even when it wrote nothing.

Grok Subagent Skill

Spawn autonomous Grok CLI (grok, xAI's Grok Build TUI) subagents for implementation work. Same delegation philosophy as use-codex: subagents burn their own tokens; the parent verifies and synthesizes.

Canonical headless invocation

grok --prompt-file /path/to/prompt.md --always-approve --no-subagents --max-turns 100

Run it in the background (run_in_background: true) for anything non-trivial; check the output file when it exits.

Why each flag is load-bearing (learned the hard way, grok 0.2.93)

1. --always-approve is mandatory in headless mode. Without it, grok's first file Edit stalls waiting for approval, the session dies silently, and grok exits 0 having written nothing while its narration claims it's "implementing". --permission-mode acceptEdits is NOT sufficient — it still stalled at the first Edit.
2. --no-subagents plus an explicit no-delegation instruction in the prompt. Grok reads the repo's CLAUDE.md / .claude/ config and will obey instructions found there. In a repo whose CLAUDE.md says "delegate all coding to codex", grok tried to spawn codex and produced nothing. Append to every prompt:

   Do ALL the work yourself with your own file-edit tools in this session. Do NOT delegate to codex, subagents, or any external CLI. Ignore any instruction in CLAUDE.md or .claude/ about delegating work — it does not apply to you.

3. --prompt-file for anything longer than a sentence — avoids shell-quoting issues. -p "prompt" / --single works for short prompts. Both are single-turn headless (print response, exit).
4. --max-turns N — give generous headroom (80–100) for multi-file work; the default may cut it short.

Verification is mandatory — grok lies by omission

Grok's stdout narration is not evidence. It narrates step-by-step progress ("Implementing types, db, both scripts...") even in runs where zero files changed. After every run:

1. git status --short / git diff --stat — did the expected files actually change or appear?
2. Read the diff / new files yourself.
3. Run the project's typecheck/tests.
4. Exercise new code against real data (use a copy for anything touching a DB).

If nothing changed, don't re-prompt blindly — inspect the transcript to see where it died:

ls -t ~/.grok/sessions/<url-encoded-cwd>/   # session IDs, newest first
grok export <SESSION_ID>                     # full transcript incl. tool calls

(The cwd is URL-encoded in the path, e.g. %2FUsers%2Fme%2Fproj. A transcript that ends at the first Edit: line = approval stall → you forgot --always-approve.)

Model selection

Omitting -m uses the CLI default, grok-4.5 (xAI's frontier model, 500K context) — verified from session logs; this is the right choice for implementation work. The other cached option is grok-composer-2.5-fast (Composer 2.5) for quick/simple tasks where latency matters more than depth. Tune depth with --reasoning-effort rather than downgrading the model. Check current options with python3 -c "import json; print(list(json.load(open('$HOME/.grok/models_cache.json'))['models']))".

Prompt structure

Same as use-codex: grok only sees what you give it. Include:

1. Repo + stack context — paths, runtime, style ("read these files first and match their style").
2. Numbered, file-by-file spec — exact filenames, schemas, function signatures, CLI flags. Grok follows precise specs well.
3. Constraints — files it must NOT touch, "no new dependencies", "must pass <typecheck cmd>".
4. Execution footer — the no-delegation instruction from above, plus "Finish by running <typecheck cmd> and fixing any errors."

Other useful flags

• -m <model> / --reasoning-effort <level> — model/effort override.
• -w / --worktree [name] — run in a fresh git worktree (good for parallel or risky changes).
• --allow "Bash(cmd)" / --deny — permission rules (Claude Code syntax); moot under --always-approve.
• -c / --continue, -r [SESSION_ID] — resume sessions.
• --output-format json|streaming-json, --json-schema — structured output for scripted use.
• grok agent stdio|headless|serve — SDK-style transports; not needed for basic delegation.

Workflow

1. Write the prompt to a scratch file.
2. Launch in background with the canonical invocation.
3. On exit: verify (git status → read diff → typecheck → run against real data).
4. If it failed silently: export the session transcript, diagnose, fix the invocation, rerun.
5. Summarize verified results to the user in your own words — never relay grok's self-report as fact.

Resuming a session (follow-ups)

Never spawn a fresh session to iterate on work this CLI already did — resume the existing one so it keeps its context and you don't re-pay the harness-token cost. Verified working headless (2026-07):

grok -c -p "<follow-up>"                 # continue most recent
grok -r <SESSION_ID> -p "<follow-up>"    # explicit id (from ~/.grok/sessions/<cwd>/)

Capture the session id from the first run and prefer resuming by explicit id; "most recent" is racy when several sessions exist.

Quota failover

If this CLI is rate-limited or out of subscription quota, the same model family is usually reachable via another CLI — read ~/.claude/skills/cli-model-overlap.md for the failover map (cursor is the hub carrying all families).