Grok Build for Claude Code

English · 한국어

A Claude Code plugin that lets Claude hand coding work to the Grok Build CLI — billed to your xAI subscription, not silently to a metered API.

Claude directs, Grok executes in your working tree, and you keep the quality gate: nothing is committed for you.

Goals: use Grok well · see where Grok is strong · Claude ↔ Grok collaboration — docs/00-product-vision.md. Reading as a human? Start at docs/08-getting-started-with-grok.md.

After install, run /grok:tour — a 15-minute guided first win, billing check included.

Quick start

Steps 1–2 run once in your terminal, and only the install command differs per OS. Step 3 runs inside Claude Code and is identical everywhere.

1. Install the Grok Build CLI (one-time)

• macOS / Linux — any shell (bash, zsh):

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

• Windows — PowerShell (e.g. a Windows Terminal tab):

  irm https://x.ai/cli/install.ps1 | iex
  

• Windows — WSL (Ubuntu, etc.): run the macOS/Linux command inside your WSL shell.

[!IMPORTANT] Windows Command Prompt (cmd.exe) is not supported by either installer — use PowerShell or WSL. Pick one side and run Claude Code on it too: a WSL install is invisible to native Windows, and vice versa.

2. Log in and smoke-test (browser OAuth, one-time)

grok login
grok --no-auto-update -p "Say ok."

This needs an active SuperGrok / X Premium+ subscription — or an xAI API key if you want metered API mode. The plugin never logs in for you and never stores a key.

3. Install the plugin — inside Claude Code

These are Claude Code prompts, not terminal commands, and are identical on every OS:

/plugin marketplace add xzawed/claude-grok-build-plugin
/plugin install grok@grok-marketplace
/reload-plugins
/grok:setup

/grok:setup confirms you're ready. Then /grok:tour walks auth → route demo → tiny sample → what to try next.

Updating

Installing is one-time; updating is three steps, and the order matters. The first two are terminal commands, not Claude Code prompts:

claude plugin marketplace update grok-marketplace   # 1. refresh the local marketplace clone
claude plugin update grok@grok-marketplace          # 2. install the new version

Then restart Claude Code and re-check /grok:status — serverVersion should be the new one.

Step 1 is not optional. /plugin marketplace add leaves a local clone registered with autoUpdate: false, so while that clone is stale, step 2 sees no new version to install (measured 2026-09-04). And claude plugin update only applies on restart: until you restart, the session keeps the MCP server process it started with.

[!NOTE] /grok:update is a different command — it updates the grok CLI, not this plugin.

What it is

• When to delegate, not just how. Claude-side routing — /grok:route and the grok-routing skill — proposes Grok for bulk, low-risk work and keeps architecture and security in Claude.
• Isolation for volume work. A delegation can run in a dedicated git worktree, so a migration, test backfill, or boilerplate pass touches nothing in your checkout until you apply it. Grok Build also spawns subagents of its own during a run.
• Subscription, not metering. By default the server strips XAI_API_KEY / GROK_CODE_XAI_API_KEY before it spawns grok, so delegated work runs inside your SuperGrok / X Premium+ plan instead of at metered API rates.
• Conventions carry over. Grok Build reads your existing CLAUDE.md / AGENTS.md and .claude/ config (skills, agents, MCP, hooks) with no extra setup.

The MCP server and its hook ship prebuilt in mcp-server/dist/, so installing the plugin needs no build step.

When to delegate — and when not

| Hand to Grok | Keep in Claude | |---|---| | Bulk, repetitive edits — one pattern across many files, renames, import fixes | Architecture and design decisions | | Low-risk volume — test backfill, docs sync, boilerplate | Security and compliance — auth, permissions, crypto, regulated domains | | Narrow, independent scope — one module, clear acceptance criteria | Anything needing whole-monorepo context | | Exploratory prototypes you were going to review anyway | The final review and quality gate |

/grok:route applies this for you and returns a nextAction — it never executes anything and never bills. Full criteria: docs/05-routing-policy.md.

Billing and approval safety

[!CAUTION] In subscription mode — the default — the server strips XAI_API_KEY and GROK_CODE_XAI_API_KEY before spawning grok, so neither of those two variables can be the credential a delegation runs on. (A model in grok's own config.toml can still carry a key of its own, through api_key or an env_key naming any other variable, or inherit one from a [model_providers.<id>] table through model_provider. The strip cannot reach that key, so the plugin reports it as billingCaveat instead — see Troubleshooting.) That is a guarantee about what the process is handed, not a claim about which credential the CLI would have picked: measured on grok 1.0.13, a live session token wins and the env key is not attempted. It becomes the fallback the moment the session is missing or expired — which is exactly when a run that began as "subscription" could quietly bill metered instead. Stripping it makes that run fail loudly rather than silently switch who pays. See docs/specs/grok-cli-contract.md §10.

• Every grok_build_delegate response reports the mode it was configured with and the billing that mode implies — a tag derived from GROK_BUILD_AUTH_MODE, not an observation of what xAI actually charged (docs/specs/grok-cli-contract.md §2).
• The server never stores or logs your credentials. It checks that your session file or key is present without reading it. It reads grok's config.toml only to note which models carry a key of their own or inherit one from [model_providers.<id>], and drops the key text on the spot (billingCaveat).
• Delegations are logged locally. Each one appends a line to ~/.grok-build/history.jsonl containing the first ~200 characters of your prompt, the working directory, and which files changed. /grok:usage and /grok:status read it back, so those previews re-enter a later Claude session. Known secret shapes are redacted before writing — but pattern matching is mitigation, not a guarantee, so treat a prompt like anything else you would not paste into a log. Delete the file to clear it; nothing else depends on it.

[!WARNING] Every delegation auto-approves all of grok's tool use — shell commands, deletions, installs, network, git — not just file edits, and non-file side effects never show up in the filesChanged diff. Headless grok cannot be relied on to edit without --always-approve (without it, a call that neither your allow rules nor grok's [ui] permission_mode approves is cancelled — stopReason: "cancelled"), so the plugin always passes it.

grok edits directly in the target cwd; the plugin never commits (it tells grok not to, and reports committed if grok does) — you review first. For riskier work, isolate the run through the tool’s own fields, not grok flags: worktree: true (the wrapper makes a real git worktree; grok’s own --worktree is a no-op under headless -p and the wrapper never passes it) and sandbox: "workspace" | "strict" | …. Both are reachable from /grok:delegate. Kernel enforcement of sandbox is Linux/macOS only.

Full rationale and verification checklist: docs/02-auth-strategy.md.

Auth modes

Chosen once, at the server level, via GROK_BUILD_AUTH_MODE — there is no per-call override.

| | subscription (default) | api (opt-in) | |---|---|---| | Trigger | unset, or =subscription | GROK_BUILD_AUTH_MODE=api | | Env handling | API keys stripped before spawn | keys passed through | | Auth source | ~/.grok/auth.json (grok login) | the API key in your environment | | Billing | xAI subscription (flat) | metered API | | Response billing | "subscription" | "metered_api" |

If you never set GROK_BUILD_AUTH_MODE, every delegation runs in subscription mode.

<details> <summary><b>API mode setup (opt-in, metered)</b></summary>

The mode is read from GROK_BUILD_AUTH_MODE in the environment that launches the MCP server. Two equivalent ways:

• Process env (recommended) — set it where Claude Code starts, so a plugin update can't overwrite it:

  export XAI_API_KEY="..."          # your own key; the plugin never issues or stores one
  export GROK_BUILD_AUTH_MODE=api
  

• .mcp.json env block — add an env to the grok-build entry (may be overwritten on a plugin update):

  "grok-build": {
    "command": "node",
    "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-server/dist/index.js"],
    "env": { "GROK_BUILD_AUTH_MODE": "api" }
  }
  

</details>

Commands

The plugin ships 27 /grok:* commands — Claude Code derives the prefix from the plugin name, grok. The 15 below are the ones you type day to day; the other 12 wrap grok's own CLI and are collapsed under the tables.

Everyday loop

| Command | What it does | |---|---| | /grok:route | Recommend Claude vs Grok + nextAction (no execution, no billing) | | /grok:plan "<task>" | Plan preview — reads files; the shell, edits and MCP tools are denied, even ones your own allow rules approve. grok enforces that, so still check planWroteFiles | | /grok:delegate "<task>" | Delegate a task; grok edits in cwd, no auto-commit | | /grok:verify "<task>" | Delegate + grok self-verification (prompt checklist) | | /grok:review | Post-edit quality gate (diff + billing; never auto-commit) | | /grok:worktree | List / diff / apply / remove / prune isolation worktrees (no auto-commit) | | /grok:resume | Continue a prior Grok session (lastSession.sessionId) | | /grok:usage | Usage summary + insights (success rate, subscription share) |

Setup, presets, passthrough

| Command | What it does | |---|---| | /grok:setup | Verify grok install + login; first-success sample + next scenarios | | /grok:status | Dashboard — ready?, billing, usage, last session, next steps | | /grok:tour | 15-minute guided tour — auth, route demo, tiny first win, next recipes | | /grok:tests | Preset: test backfill / expansion | | /grok:migrate | Preset: mechanical multi-file migration | | /grok:boilerplate | Preset: scaffold / boilerplate | | /grok:cli "<raw grok args>" | Passthrough: any grok subcommand under the billing-safe env |

<details> <summary><b>The other 12 — grok's own CLI verbs</b></summary>

| Command | What it does | |---|---| | /grok:sessions | List, search, or delete Grok sessions (no restore — use /grok:resume) | | /grok:export | Export a Grok session transcript as Markdown | | /grok:memory | Manage Grok cross-session memory | | /grok:inspect | Show the configuration Grok discovers for this directory | | /grok:models | List available Grok models | | /grok:mcp | Manage Grok's MCP server configurations | | /grok:login | Guide the one-time terminal login (never runs it for you) | | /grok:logout | Sign out and clear cached credentials | | `/gro