Grok Build: xAI's AI Coding Agent CLI Explained (2026)

Grok Build is the piece of xAI's developer stack that people actually search for by name, and it has changed more in the last ten weeks than in the two months after launch. It went from early beta to a 1.0 release, got open-sourced under Apache 2.0, survived a genuinely serious data-handling incident, and swapped its default model. This guide is written against the state of the product on 23 August 2026, with every figure taken from xAI's own documentation or a source linked inline.

We cover what Grok Build is, what plan you need and what it costs, the concrete first-run steps, how Skills and Connectors work (with a real worked example), the limits and gotchas worth knowing before you point it at a private repo, and how it stacks up against Claude Code, Codex CLI, and Cursor.

What is Grok Build?

Grok Build is xAI's agentic coding CLI. The official documentation describes it as "a powerful and extensible coding agent" that you can run three ways:

• Interactive TUI — cd into a project and run grok. A full-screen, mouse-interactive terminal UI.
• Headless — grok -p "Explain this codebase" for scripts, CI, and bots.
• ACP — grok agent stdio runs it as an Agent Client Protocol agent over JSON-RPC, so editors and other apps can drive it.

Underneath, it is a Rust program. When xAI open-sourced it in mid-July 2026 under the Apache 2.0 licence, the release covered the agent loop (context assembly, response parsing, tool dispatch), the tool layer (reading, editing, searching code), the terminal UI, and the extension system for skills, plugins, hooks, and MCP servers. The model itself is not open source — the harness is designed to point at any API or local inference endpoint. The repository lives at github.com/xai-org/grok-build and has picked up roughly 25.9k stars.

The signature architectural bet is parallel subagents. Grok Build can run up to eight concurrent subagents, and — importantly — each one sits inside its own isolated git worktree. That is not a cosmetic detail: when two agents touch the same file, git reconciles them rather than letting one silently clobber the other in a shared directory.

Three operating modes govern how much autonomy you hand over: code (edits and runs commands automatically), plan (produces an execution plan and diffs, waits for your approval), and ask (read-only exploration).

One thing to be clear about, because a lot of coverage still repeats it: Arena Mode has not shipped. The idea — several agents compete on the same task and an automated evaluation pass ranks the outputs before you review them — has been discussed by xAI since mid-2026 but is still a roadmap item. You are currently paying for the architecture that would make Arena Mode possible, not for Arena Mode.

What changed in Grok Build in July and August 2026?

This is the section most readers land here for, because the product has moved fast. Here is the compressed timeline, with versions from the Grok Build release tracker:

If you installed Grok Build during the beta and have not updated since July, you are running a materially different product. Two of those changes matter more than the rest: the 1.0 release itself, and the July privacy remediation covered below.

What does Grok Build cost, and what plan do you need?

There is no standalone Grok Build subscription. The CLI is free to install; using it requires an active SuperGrok or X Premium+ subscription. SuperGrok is around $30/month and SuperGrok Heavy around $300/month, with higher allowances at the top tier.

The billing model is the part people get wrong. xAI does not meter Grok Build separately. Per the official Grok FAQ, subscribers get "one flexible weekly usage pool that works across all Grok products" — Chat, Imagine, Voice, Build, and API all draw from the same bucket, and "different products cost different amounts depending on how much compute that product requires." A long coding run is expensive in pool terms; a chat message is not.

You can watch it burn down under Settings → Usage, which shows a progress bar, a per-product breakdown, your reset date, and any Extra Usage Credits balance. When the weekly limit is hit, "paid features will pause until your weekly limit resets" — you can buy Extra Usage Credits, upgrade, or enable Auto Top Up to keep going.

If you would rather pay per token, the same models are on the xAI API. Current published pricing:

Those rates apply to prompts under 200k tokens. At 200k and above, every line doubles — grok-4.6 becomes $4.00 input / $1.00 cached / $12.00 output per million. That cliff is worth designing around if your agent sessions accumulate long contexts.

Two notes on the cached-input line, because it is the number that actually governs agent cost: a Skill re-sends the same instruction block every turn, so cache pricing dominates a long session. Grok 4.6 raised cached input from $0.30 to $0.50 per million versus 4.5 — a 67% increase on exactly the token class agents lean on hardest.

How do you get started with Grok Build?

The full first run is about four commands.

# macOS / Linux / WSL
curl -fsSL https://x.ai/cli/install.sh | bash

# Windows (PowerShell)
irm https://x.ai/cli/install.ps1 | iex

# then, inside a project
cd ~/code/my-project
grok

The first launch opens a browser for authentication against your xAI account. In a headless or container environment where no browser exists, set an API key instead:

export XAI_API_KEY="xai-..."

From there, the useful first moves are /tutorial (the built-in onboarding added in v0.2.112), /doctor to check your environment, and switching to plan mode before you let it touch anything. Settings persist to ~/.grok/config.toml (%USERPROFILE%\.grok\config.toml on Windows). The settings reference documents the shape — a [models] table with default and web_search keys, per-model tables like [model."grok-4.6"] carrying base_url, temperature, top_p, max_completion_tokens and context_window, and a [ui] table with compact_mode, theme, and show_thinking_blocks. Project-level configs are deliberately restricted to MCP servers, plugins, and permission rules — a repo you clone cannot rewrite your whole agent config.

For scripting, headless mode is the surface you want:

grok -p "List TODO comments" --output-format json
grok -p "Explain the architecture" --output-format streaming-json
grok -p "Run the test suite and fix failures" --always-approve --no-auto-update

--output-format takes plain, json, or streaming-json. Sessions are addressable with -s/--session-id, -r/--resume, and -c/--continue. In CI, always pass --no-auto-update (or set auto_update = false in config) so a background version check does not interfere with the run. Our step-by-step setup walkthrough is in How to install Grok Build CLI.

What are Grok Skills, and how do you build one?

A Skill is a folder containing a SKILL.md file: reusable instructions Grok loads on demand instead of you re-pasting the same prompt. The docs spell out exactly where Grok looks for them:

• ./.grok/skills/ — traversed upward to the repo root, so project skills live in the repo
• ~/.grok/skills/ — your personal, cross-project skills
• a plugin's own skills/ directory
• any custom path listed under [skills] paths in ~/.grok/config.toml

The frontmatter keys are a short, documented list: name (defaults to the directory name), description (defaults to the first body paragraph), when-to-use (alias when_to_use) for trigger phrases, paths for gitignore-style conditional visibility, allowed-tools, argument-hint for slash-command autocomplete, user-invocable (default true), and disable-model-invocation to restrict a skill to manual use. Unrecognised keys are ignored.

A real one — a PR-description skill at .grok/skills/pr-description/SKILL.md:

---
name: pr-description
description: Draft a pull request description in our house format
when-to-use: When asked to open a PR, write a PR body, or summarise a branch
argument-hint: [base-branch]
allowed-tools: [read, bash]
user-invocable: true
---

Diff the current branch against the base branch (default `main`).
Then produce a PR description with exactly these sections:

## What changed
Three bullets maximum. Plain language, no file paths.

## Why
One paragraph tying the change to the issue it closes.

## How to verify
Numbered steps a reviewer can run locally, including the exact
test command. If no test covers the change, say so explicitly.

Never invent an issue number. If you cannot find one in the branch
name or commit messages, leave the field blank.

Because user-invocable is true, this becomes the slash command /pr-description automatically. Set disable-model-invocation: true if you want it to fire only when you ask, never when the model decides it is relevant.

Grok also ships five built-in skills maintained by xAI: Word Documents, Presentations, Spreadsheets, PDFs, and a Skill Creator that scaffolds new skills for you. Plugins load from ./.grok/plugins/, ~/.grok/plugins/, marketplace installs, or --plugin-dir <PATH>, and everything is manageable from the extensions modal via /plugins, /hooks, /skills, and /mcps. There is a Marketplace tab in the TUI for browsing and installing from configured sources.

Do Claude Code skills work in Grok Build?

Yes, and this is the deliberate strategic choice in the whole product. xAI's documentation states plainly that "Grok is fully compatible with Claude Code with zero configuration needed" — it automatically discovers Claude Code marketplaces, plugins, skills, MCPs, agents, hooks, and instruction files without any setup. Rather than compete with Anthropic's skills ecosystem, xAI imported it.

The practical implication for anyone writing internal agent context today: write it once, in the portable format, and it runs in both stacks. Our AGENTS.md guide covers how to structure instructions that survive being read by more than one agent.

What connectors does Grok support?

Connectors are first-party integrations that let Grok read from and write to the apps you already use. They live on the Grok side (web, iOS, Android) rather than inside the CLI, and most of them are implemented as hosted MCP endpoints. As of 12 August 2026 the catalogue stands at 31 integrations across 8 categories, with 28 visible as in-app tiles:

• Featured — Box, Canva, GitHub, Gmail, Google Calendar, Google Drive, Notion, Stripe, Vercel, Wix
• Productivity — Calendly, Figma, Gamma, HyperFrames by HeyGen, Linear, Microsoft Teams, Outlook, Outlook Calendar
• Business & enterprise — OneDrive, Salesforce, SharePoint
• Finance — eToro, Interactive Brokers, S&P Global, Webull
• Developer — Excalidraw, Mixpanel
• Sales — HubSpot, Meltwater
• Analytics — Google Cloud BigQuery
• Advertising — X Ads

Connectors launched on 6 May 2026 with GitHub, Notion, Linear, Google Workspace, Microsoft 365, and Bring-Your-Own-MCP; Vercel, Canva, Gamma, and S&P Global arrived on 22 May. Stripe, Box, Wix, Figma, and the finance cluster are later additions. On 10 August 2026 xAI added a Voice connector, merging Voice Mode with Connectors so you can speak a request and have Grok pull from a connected app and answer aloud.

Can you connect your own MCP server?

Yes, and inside Grok Build this is arguably more useful than the hosted catalogue. Per the MCP documentation, you can register servers from the CLI:

grok mcp add <name> -- <command>              # stdio (local process)
grok mcp add --transport http <name> <url>   # remote HTTP server

Or declare them in ~/.grok/config.toml:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
headers = { "x-mcp-session-id" = "{{session_id}}" }

Environment variables expand with ${VAR} and ${VAR:-default} across config fields. Timeouts are tunable via startup_timeout_sec (default 30) and tool_timeout_sec (default 6000). Repo-level servers override user-level ones of the same name. And, in keeping with the compatibility theme, Grok Build reads existing Claude, Cursor, and plain .mcp.json configurations — if you have already wired an internal MCP server for another agent, it appears here for free. The one constraint on the connector side: a custom MCP server used through the Grok apps must be reachable over the public internet, so a local-only deployment needs a tunnel.

Where are the official Grok Build docs?

The canonical documentation is at docs.x.ai/build/overview. It is organised roughly as:

• Overview — what Grok Build is, install commands, the three run modes, authentication
• Settings — the full ~/.grok/config.toml reference: model tables, UI options, project-config scoping
• Headless & scripting — every CLI flag, output formats, session management, CI guidance
• Skills, plugins & marketplaces — skill discovery paths, SKILL.md frontmatter, plugin loading, the extensions modal
• MCP servers — grok mcp add, TOML syntax, stdio vs HTTP transports, timeouts, env expansion
• Hooks — lifecycle hooks including PreToolUse, PostToolUse, and SessionStart, with shell and HTTP runners plus allow/deny results

Two adjacent pages are worth bookmarking: docs.x.ai/docs/models for live API pricing and context windows, and docs.x.ai/grok/faq for how the weekly usage pool works. The source itself is often the fastest answer — the GitHub repository ships a docs/user-guide/ tree alongside the Rust crates.

What are Grok Build's limits and gotchas?

The July 2026 repository-upload incident is the one you need to know about. On 12 July, an independent researcher publishing as cereblab demonstrated that Grok Build 0.2.93 was uploading entire local git repositories — untracked files, full commit history, and unredacted secrets from .env files — to a Google Cloud Storage bucket named grok-code-session-traces via a /v1/storage endpoint. The wire-level analysis put it at roughly 5.10 GB across 73 chunks against about 192 KB of task-relevant model traffic in the same session. xAI disabled the uploads server-side within a day, and on 14 July published a response documenting zero-data-retention mode and a /privacy command that lets you inspect settings, disable retention, and delete previously synced data; Elon Musk publicly pledged deletion of data uploaded before that point.

The behaviour is fixed and the config flag (disable_codebase_upload) exists. But if you are pointing an agent at a private repo, run /privacy and confirm your settings before the first session rather than after — and treat the episode as a reason to prefer per-project API keys and repos without committed secrets. Do not assume, as earlier write-ups did, that a local-first CLI keeps everything local.

Beyond that:

• Arena Mode is still unshipped. Parallel breadth is real; automated ranking of the competing outputs is not. You review eight branches yourself.
• Context is 500k, not 1M. Grok 4.6's window is half of what Claude Code offers, and prompts crossing 200k tokens double your API rate.
• Cached-input pricing went up 67% with the 4.6 default. If you tuned a Skills library for cost under 4.5, re-measure.
• Subagent spawning was resource-unbounded until v1.0.1 fixed file-descriptor exhaustion. Update if you run wide fan-outs.
• Usage is a shared weekly pool. A heavy Grok Imagine week can eat the budget you wanted for coding.

Grok Build vs Claude Code, Codex CLI and Cursor — which should you use?

An honest, current read:

Cost per unit of work is Grok Build's strongest argument. In Composio's 50-hour hands-on comparison, Grok Build averaged $2.49 per completed task against Claude Code's $11.80 — roughly a fifth of the cost. It also routes to other models through OpenRouter, including Claude, GPT, Gemini, and local endpoints, which Claude Code does not do natively. Composio's overall verdict was still that Claude Code wins for production work and Grok Build suits "bulk test writing or anything I would sandbox anyway."

Claude Code wins on maturity and reach. A 1M-token window, a longer security track record, and availability across terminal, IDEs, desktop, web, mobile, and Slack. If one agent has to be your default, this is still the low-regret pick.

Codex CLI wins on bundling. The CLI is open source and free; the compute comes with a ChatGPT Plus or Pro subscription you may already have, and it leans harder on the cloud-sandbox-to-pull-request pattern than on interactive terminal work.

Cursor is now a sibling product, not a rival. SpaceX agreed in June 2026 to buy Anysphere, Cursor's parent, in a $60 billion all-stock deal, and the acquisition closed on 14 August, folding Cursor into the SpaceXAI division alongside xAI. Grok 4.6 shipped on Cursor the same day it shipped in Grok Build. Expect the two to converge — which is a reason to weight the ecosystem bet rather than the current feature diff.

On raw model quality, xAI's own Grok 4.6 announcement reports an Artificial Analysis Intelligence Index score of 61 (matching GPT-5.6 Sol), 69.9% on CursorBench v3.2, and 65.9% on DeepSWE v1.1. Note that the widely-quoted 70.8% SWE-bench Verified figure belongs to grok-code-fast-1, the model Grok Build launched on in May — not to the current default. We unpack the 4.6 benchmark picture separately in our Grok 4.6 launch guide, and run the three CLIs head-to-head in Grok Build vs Claude Code vs Codex CLI.

So should you adopt Grok Build?

A decision rule rather than a verdict:

• Already paying for SuperGrok or X Premium+? Install it today. The marginal cost is zero and the Claude Code compatibility means your existing skills and MCP configs work unchanged.
• Running high-volume, well-scoped, sandboxable work — test generation, migrations, mechanical refactors across many files? The eight-worktree fan-out and the ~5x cost advantage are real, and this is where Grok Build earns its place.
• Picking one primary agent for a team, from scratch? Claude Code remains the lower-risk default on context, maturity, and surface coverage. Revisit once Arena Mode ships and the Cursor integration lands.
• Working with regulated or secret-bearing repositories? Run /privacy first, confirm zero-data-retention, and pilot on a non-sensitive repo before you commit.

The broader point is that the coding-agent field has converged on the same four pieces — a CLI, skills, connectors, and MCP — and the differentiation has moved to price per completed task, context, and ecosystem gravity. For the full landscape, see our complete guide to AI coding agents. And if you are trying to work out how much of your delivery pipeline should be agent-driven versus human, that is a staffing question as much as a tooling one — the kind of thing our engineering teams get asked about weekly.

FAQ

What is Grok Build?

Grok Build is xAI's terminal-based AI coding agent — a CLI that reads your codebase, edits files, runs shell commands, and can spawn up to eight subagents in isolated git worktrees. It runs as an interactive TUI, headlessly with grok -p, or as an ACP agent inside other editors. It reached version 1.0 on 7 August 2026 and is open source under Apache 2.0.

Is Grok Build free?

The CLI itself is free to install and its source is Apache 2.0 licensed, but running it is not free. You need an active SuperGrok or X Premium+ subscription, or an xAI API key billed per token. There is no free tier for Grok Build usage, and no standalone Grok Build subscription separate from the Grok consumer plans.

What plan do I need for Grok Build?

SuperGrok (around $30/month) or X Premium+ is the minimum; SuperGrok Heavy (around $300/month) gives the largest allowance. All Grok products — Chat, Imagine, Voice, Build, and API — draw from one shared weekly usage pool, so a long coding run consumes far more of it than a chat message. Check Settings → Usage for your remaining balance and reset date.

What are Grok Skills?

Skills are folders containing a SKILL.md file with YAML frontmatter and markdown instructions, loaded on demand so you stop re-pasting prompts. Grok discovers them in ./.grok/skills/, ~/.grok/skills/, plugin directories, and custom paths. User-invocable skills automatically become slash commands. Five skills ship built in: Word Documents, Presentations, Spreadsheets, PDFs, and Skill Creator.

Are Claude Code skills compatible with Grok Build?

Yes. xAI's documentation states that "Grok is fully compatible with Claude Code with zero configuration needed" — it automatically discovers Claude Code marketplaces, plugins, skills, MCP servers, agents, hooks, and instruction files. Grok Build also reads existing Claude, Cursor, and .mcp.json MCP configurations, so an internal MCP server you already wired for another agent works immediately.

What connectors does Grok support?

As of 12 August 2026 the catalogue holds 31 integrations across 8 categories, including GitHub, Gmail, Google Drive, Google Calendar, Notion, Linear, Stripe, Box, Vercel, Wix, Canva, Figma, Salesforce, SharePoint, OneDrive, Outlook, Microsoft Teams, HubSpot, BigQuery, and S&P Global. Bring-Your-Own-MCP covers anything else, provided the server is reachable over the public internet.

Grok Build vs Claude Code — which should I use?

Claude Code is the safer default: 1M-token context, a longer security record, and availability across terminal, IDEs, desktop, web, mobile, and Slack. Grok Build wins on cost — one hands-on comparison measured $2.49 per completed task versus $11.80 — and on parallel fan-out across isolated worktrees. Use Claude Code as primary, Grok Build for high-volume sandboxable work.

Is Grok Build safe to point at a private repository?

It is now, with a caveat. In July 2026 a researcher showed version 0.2.93 uploading entire git repositories, including unredacted .env secrets, to an xAI storage bucket. xAI disabled the uploads server-side, shipped a /privacy command and a disable_codebase_upload flag, and documented zero-data-retention mode. Run /privacy and verify your settings before your first session on sensitive code.

What is the latest version of Grok Build?

Version 1.0.5, released 15 August 2026, adding config overrides, worktree cleanup, hook status messages, and right-to-left terminal text. The 1.0.0 milestone landed on 7 August after roughly 100 beta updates in ten weeks, and v1.0.4 on 13 August switched the default model to Grok 4.6. Check grok --version and update if you installed during the beta.