How to use Grok CLI with Claude Code

Use Grok as a bounded worker, not a second conductor

xAI's terminal coding agent is Grok Build and its executable is grok. It has an interactive interface, a headless mode, and tools that inspect and change a codebase. From Claude Code the integration is ordinary shell delegation: Claude writes a narrow prompt, runs grok -p, reads stdout, and decides whether the answer is worth anything.

No plugin is involved. The shell is the bridge. This works when the task has a compact input and an observable output: finding the likely owner of a bug, summarizing a directory, extracting a JSON inventory, drafting several independent approaches. Claude keeps the requirements, the user conversation, and responsibility for the final integration.

A short headless call is not a safety boundary. Grok is a coding agent, not a text generator; its documented tools include file edits and shell commands. Your prompt and approval mode decide what it will attempt. Operating-system and repository permissions decide what it can actually change. Only the second one is enforcement.

Install Grok Build and test headless mode

xAI ships an install script. Run it, complete the documented authentication flow, then test a one-shot prompt from a disposable or read-only directory. Do that before you wire it into an active Claude Code session, not after.

curl -fsSL https://x.ai/cli/install.sh | bash

-p, also documented as --single, submits one prompt in headless mode and exits when the response finishes. That exit is what makes it orchestrable: stdout can be redirected, parsed, or pasted back into the parent conversation.

grok -p "Map this repository's authentication flow. Do not edit files. Return the five most relevant files and one sentence about each."

Run it from the repository you want inspected, or name the directory with --cwd. Use the explicit form once Claude Code is coordinating several worktrees, where an implicit working directory is a coin flip.

grok --cwd /path/to/worktree -p "Find the code path that retries failed uploads. Do not modify the tree."

Pin the model and reasoning effort

Pin the model with -m when reproducibility matters, or when your team has standardized on one xAI model for a class of task. --effort requests a reasoning level. xAI's headless documentation lists none, minimal, low, medium, high, xhigh, and max as the canonical set, and says only the levels a given model advertises are accepted.

grok -m <model-id> --effort high -p "Explain the deadlock risk in src/queue. Do not edit files. Cite symbols and paths."

Never hard-code a model ID copied from an old article. The lineup changes, and the model picker in your own installation is the only source of truth. A rejected effort level means a configuration mismatch, not a broken headless mode.

Higher effort needs a reason. A dependency scan or a draft outline gains more from a narrower prompt than from maximum reasoning. Spend the extra latency and usage on cross-file inference, real ambiguity, and hard debugging.

Return structured output with JSON Schema

--json-schema constrains Grok's final answer to a JSON Schema you supply. xAI added it for workflows where a script needs machine-readable output rather than prose. It beats asking for JSON in the prompt, because the contract is enforced instead of requested.

SCHEMA='{"type":"object","properties":{"files":{"type":"array","items":{"type":"string"}},"risk":{"type":"string"},"next_step":{"type":"string"}},"required":["files","risk","next_step"]}'

grok -p "Triage the failing upload test. Do not edit files." --json-schema "$SCHEMA" > grok-triage.json

Keep the schema small. Require only the fields the next step actually reads, use enums for fixed categories, and park narrative evidence in one bounded string field. Deep schemas mostly buy you useful answers that fail validation.

Structure is not correctness. Claude still has to open the cited files, check the important claims, and throw out anything that contradicts the repository. Schema validation proves shape. It proves nothing about truth.

Generate several independent drafts

The current CLI reference, changelog, and published source document no --best-of-n option. Unofficial examples show one; do not copy it. If you want several candidates, run several explicit one-shot calls and label each prompt so the outputs stay auditable.

for n in 1 2 3; do
  grok -p "Draft option $n for the migration plan. Focus on rollback, keep it under 400 words, and do not edit files." > "draft-$n.md"
done

The loop produces three candidates and ranks none of them. Have Claude score the drafts against a rubric: correctness, rollback safety, operational complexity, fit with the stated constraints. An explicit evaluation step is honest in a way that pretending a CLI switch did the selecting is not.

Independent draft calls pay off on cheap exploration: names, outlines, test matrices, candidate root causes. They stop paying when each answer needs the full conversation, or when the task turns on product taste nobody wrote down. Keep that work in the agent that already holds the context.

Use unattended tool approval carefully

--always-approve, also exposed as --yolo, approves every tool execution automatically. xAI's permissions documentation calls it a bypass-permissions mode and notes that deny rules, hooks, and administrator locks still apply on top. It is useful for unattended automation in exactly one situation: when the environment was built to contain the mistake.

grok --cwd /path/to/disposable-worktree --always-approve -p "Update only the generated fixture snapshots, run the focused test, and stop if any source file changes."

A safer unattended setup: disposable worktree or container, clean starting commit, narrow credentials, explicit deny rules, mandatory post-run diff review. Capture stdout and the exit status. Put a time limit in the job runner, outside the agent. When it finishes, Claude reads git status, opens every changed file, and runs the verification itself.

There is no --check self-verification flag. In the official CLI reference --check belongs to grok update, where it checks for an available CLI update. Build verification into the prompt and the wrapper, and let tests outside the agent be the authoritative gate.

Choose tasks by reversibility and verification cost

Grok earns its place when iteration speed matters and a weak first answer costs nothing to throw away. Repository scouting, issue triage, dependency mapping, log summarization, throwaway experiments, test-case brainstorming, first drafts: every one of those produces output Claude can check. The worker saves time without ever becoming the authority.

Be slower to delegate correctness-critical work: authentication, payments, data migrations, concurrency, signing, deployment controls. Speed does not substitute for source-backed reasoning and a passing test. Taste-critical work has the same problem from the other direction. Product voice, interaction design, information hierarchy, and genuinely nuanced tradeoffs stay with whoever holds the full brief.

A shell workflow keeps the whole contract visible: prompt, working directory, flags, captured output, verification. Once Claude is asking repeated follow-ups, one-shot calls have stopped being the right tool. Move to an interactive Grok session or a documented session handoff instead.

Questions people ask

Keep reading