Grok Build

Grok Build is xAI's terminal coding agent. You install it with one command, run grok in a project folder, and it reads, edits and tests code with plan mode, subagents, skills, hooks and MCP servers. xAI's pricing page lists Free ($0), Plus ($8), Premium ($30), Super ($100) and Ultra ($200) a month. We checked every fact below on 31 October 2026 from the vendor's own pages.

At a glance

What Grok Build is

xAI's docs open with a plain description: "Grok Build is a powerful and extensible coding agent." You can use it in three ways. The first is an interactive terminal app that the docs call a rich, mouse-interactive, fullscreen experience. The second is headless, where you pass a prompt with -p and get text or JSON back. The third is through the Agent Client Protocol, which lets other apps host the agent.

The product page says the agent is "now powered by Grok 4.7, our newest model." It frames the pitch as a coding agent for complex work that "works with any codebase, any language."

Naming is worth a note. xAI's documentation index is titled "SpaceXSI API Documentation" and says it is the official developer documentation of SpaceXSI (xAI). The footer of x.ai reads "SpaceX Super Intelligence LLC." We use "xAI" for the maker because the docs use both names together, and we do not say more about ownership than those pages do.

Grok Build sits in the same group as Claude Code, OpenAI Codex CLI, Gemini CLI and OpenCode. All of them are agents that live in a shell and work on a repository you already have. If you are new to the idea, our guide to choosing a coding agent explains the trade-offs.

Who it suits

Grok Build fits developers who are comfortable in a terminal and want an agent they can point at a repo, script in CI, or run in parallel on several tasks. The feature set leans toward people who already work with rules files, hooks and plugins, because the docs treat those as first-class.

It also fits people who already pay for an X or Grok plan. Plus and above list Grok Build alongside Chat, Voice and Imagine in one shared usage pool, so there is no separate coding subscription to buy.

Teams get their own set of controls. The enterprise docs cover single sign-on, managed config files, pinned security settings and zero data retention, which we cover below.

It fits less well if you want a visual app builder. Grok Build edits files in your project. It does not host an app for you or give you a drag-and-drop editor. Our best vibe coding tools list covers that other category.

Pricing

xAI sells one subscription ladder for all of its products, and Grok Build is one of them. The pricing page headline is "One subscription. Access to everything."

Prices exclude taxes. The page says plans can be cancelled at least 24 hours before renewal.

How usage works

The pricing FAQ says every tier "includes a pool of AI usage shared across Grok and Cursor." Within Grok, the pool covers Chat, Imagine, Voice and Bot, and the page lists Build as a product in the plan table. Higher tiers get bigger pools, and "usage costs vary by product."

Allowances refresh weekly. If you reach your limit you can buy top-ups or wait for the refresh. Remaining usage shows in settings, and inside Grok Build the /usage command shows credit use and billing.

The pricing page does not publish a number of tokens or requests per plan. It gives multiples of the Plus pool instead. We can tell you Premium has 4x Plus, but not what Plus is in tokens.

The API is billed separately

Paid plans include Grok API access, but API usage "is billed separately at standard model rates and doesn't draw from your plan's usage pool." That matters if you run Grok Build headlessly with an API key in CI. The key path bills the API account, not your plan.

The models page lists the API rates. A few that apply to coding:

Requests that reach the threshold are billed at the higher rate for all tokens in the request. The models page calls Grok 4.7 the most capable model xAI has built and recommends it for code.

Third-party models

The pricing FAQ says the self-serve plans "include generous usage of Grok models but do not include an allowance for third-party models." Third-party models stay available in Cursor at API list prices. The page ties that to Cursor, not to Grok Build, so we do not assume the terminal agent can bill third-party models through your plan.

Install and first run

The install command for macOS and Linux is:

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

Windows uses irm https://x.ai/cli/install.ps1 | iex in PowerShell. The enterprise page also names an npm route, npm install -g @xai-official/grok, for sites that cannot reach the script host.

Then cd into a project and run grok. On first launch it opens a browser to sign in. On a machine with no browser you can export an API key instead, or run grok login --device-auth, which prints a URL and a short code you finish on another device.

The docs suggest two first prompts: "Explain this repo," and an @ file reference such as "Walk me through this file." The @ syntax adds a file to context.

grok inspect is a useful second command. It lists what Grok found in the current directory: config sources, instruction files, skills, plugins, hooks and MCP servers, with approximate token counts for rules.

How it works

Modes

The docs describe four session modes and Shift+Tab cycles through them.

• Normal asks before it runs tools that are not already allowed.
• Plan lets only the session plan file be edited until you approve.
• Auto uses a classifier to approve safe tools, when the feature is on.
• Always-approve skips permission prompts, though deny rules and hooks still apply.

Plan mode deserves its own mention. The agent explores the repo and drafts a plan, then a preview opens. You press a to approve, s to request changes, or c to comment on a line. The docs say plan mode gates edit tools, not the shell, so a plan can still run read-only commands that your permission mode allows.

Goals and workflows

/goal hands the agent an objective and lets it work across many rounds. After each round it decides whether to continue, stop for input or call the goal done. When it thinks it is done, a panel of reviewer subagents checks the work against evidence, and the goal completes only when most agree. You can cap spend with --budget <tokens>.

The docs give good advice here: state what done looks like. "Migrate the auth module to the new API, verified by the auth test suite passing, without changing public endpoints" beats a vague goal.

Workflows are saved scripts that fan out a bounded set of subagents, verify, then return a result. /create-workflow writes one, and it is saved as a .rhai file in .grok/workflows/. /deep-research runs a built-in research workflow. Both can be switched off in config.

Subagents and worktrees

Subagents are child sessions with their own context that return a summary. There are three built-in types: general-purpose, explore (read, list and search only) and plan. You can add types under .grok/agents/.

Worktrees give parallel agents separate checkouts. grok -w starts a session in an isolated git worktree under ~/.grok/worktrees/<repo>/<name>, starting from your current HEAD including uncommitted changes. The product page adds that you can launch subagents in their own worktrees.

Rules, skills, hooks and plugins

Project rules go in AGENTS.md. Grok also reads CLAUDE.md, .cursor/rules/ and .claude/rules/ for compatibility, and a nested file applies to its subtree. Files load in full with no size cap, so keep them short.

Skills are reusable instruction sets, called by name or invoked when a task matches. The product page says /skillify captures a session as a new skill. Plugins bundle skills, agents, hooks and MCP servers behind one install, with a marketplace or any git repo as the source. Hooks run scripts on file edits and tool calls.

The /import-claude command opens a modal to import Claude settings, which makes switching in from Claude Code less painful.

Other built-in tools

The product page lists code search, multi-file edits, git integration, web search, terminal execution with streaming, background tasks, memory that persists across sessions, and line-by-line code review. The command table adds /imagine and /imagine-video for media generation and /loop for recurring prompts. These need their features enabled.

Models used

Grok Build's default is Grok 4.7 according to xAI's product page, and the demo terminal on that page shows grok-4.7. The models page lists older models too, including grok-4.6, grok-4.5, grok-4.3 and a grok-build-0.1 model with a 256k context.

The config key [models] default sets the model for new sessions, and /model <name> switches inside a session. /effort sets reasoning effort when the model supports it. You can restrict the picker with allowed_models, hide models with hidden_models and remove them with disabled_models.

Custom models are a first-class feature. A [model.my-model] block takes a model id, a base URL, a display name and an environment variable for the key. The settings reference describes these as bring-your-own-key entries for OpenAI-compatible or Anthropic Messages endpoints. Credential order is per model: model.api_key, then model.env_key, then the active session token, then XAI_API_KEY.

You can also route models per subagent through [subagents.models], which helps if you want a cheaper model for exploration.

For model details on our site, see Grok 4.7 and the xAI host page.

Integrations and MCP support

Grok Build supports MCP in full. Tools from a server appear next to built-in tools, named <server>__<tool>.

grok mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir
grok mcp add --transport http linear https://mcp.linear.app/mcp

The first adds a local stdio server. The second adds a remote HTTP server, and the docs say OAuth is handled automatically. A static --header is available for token auth. grok mcp list, remove and doctor manage servers, and doctor diagnoses config and connectivity.

Servers can live in ~/.grok/config.toml or, with --scope project, in the repo's .grok/config.toml so they ship with the code. The docs set a default 30 second startup timeout and a 6,000 second tool timeout, both adjustable. OAuth tokens sit in ~/.grok/mcp_credentials.json.

Compatibility is generous. Grok also loads MCP config from ~/.claude.json, .cursor/mcp.json and project .mcp.json, merged below its own config. You can turn that off per vendor.

The product page names Linear, Sentry, Grafana and Postgres as examples. Our own Linear MCP and Sentry MCP pages cover two of those. For background on the protocol, read what MCP servers are.

Privacy, security and data handling

Most of what xAI says about data sits in the enterprise page.

• Network. All traffic is HTTPS on port 443 with TLS 1.2 or 1.3. Required hosts are cli-chat-proxy.grok.com for inference and auth.x.ai for sign-in. code.grok.com is used for session sync and sharing and can be blocked, which leaves sessions local only.
• Session lifecycle. Prompts and file content are assembled locally, sent to an inference proxy, and tools run locally in your sandboxed environment.
• Zero data retention. ZDR is enforced per team. When it is on, "no prompts, code, or responses are persisted at the inference layer." Video tools under ZDR need your own storage bucket.
• Local history. Session history is stored in ~/.grok/ on your machine.
• Privacy controls. /privacy shows or toggles privacy and data-retention status in the TUI.

The pages we read do not state what is retained or used for training for personal accounts. If you are not on a ZDR team, check the privacy policy and /privacy before you send sensitive code.

Permissions and the sandbox

Permissions decide whether a tool call runs. The sandbox limits what an approved call can touch. They are separate, and the docs say so clearly.

Allow and deny rules take patterns such as Bash(git *). Deny always wins. A remembered "always allow" still prompts for dangerous patterns like rm and git push, but an explicit config or CLI allow rule auto-approves them.

The sandbox is off by default. Profiles are off, workspace, devbox, read-only and strict. It uses Landlock on Linux and Seatbelt on macOS.

Enterprise controls

Config loads from five layers, and /etc/grok/requirements.toml pins settings that users cannot override. Login can be forced through enterprise OIDC, an external auth provider, or a team UUID. A disable_bypass_permissions_mode setting turns always-approve off across a deployment. Headless modes include dontAsk, which silently denies anything not explicitly allowed.

Limits and gotchas

• The sandbox is off by default. You must opt in with --sandbox or config.
• Child-network limits are Linux only. The docs say this is enforced on Linux and is a no-op on macOS for the read-only and strict profiles.
• Built-in profiles do not protect credentials. Paths such as ~/.ssh need a custom deny list.
• `~/.grok/` stays writable under sandboxed profiles, so sessions can persist.
• Model calls bypass the sandbox network rules. The model API and web tools are not blocked by child-network settings.
• Plan mode does not stop the shell. It gates edit tools only, and subagents are not edit-gated by the parent's plan mode.
• Always-approve is powerful. Deny rules and hooks still apply, but little else stops a tool call.
• Worktrees pile up. They persist after sessions end until you run grok worktree rm or gc.
• Usage numbers are relative. The pricing page gives multiples of Plus, not token counts, and says costs vary by product.
• Some commands are feature-gated. /auto, /imagine and /loop appear only when their features are available.

How it compares with peers

We already compare the incumbents in Claude Code vs Codex and Cursor vs Claude Code. Prices across tools are in the pricing comparison.

The most visible design choice is how much Grok Build copies from the existing ecosystem on purpose. It reads CLAUDE.md, Cursor rules and Claude and Cursor MCP files, and it imports Claude settings. That lowers the cost of trying it next to another agent. The other choice is the subscription: coding usage comes out of the same pool as chat and image generation, so heavy coding can use up an allowance that you also wanted for other things.

Who should pick something else

• People who want a visual builder. Try Lovable or Bolt.
• Editor-first developers. Cursor or Windsurf keep you in a graphical editor.
• Teams that want a published retention statement for individuals. The pages we read only give ZDR terms for teams.
• Anyone who needs exact per-plan token counts. xAI does not publish them on the pricing page.
• Teams already standardised on another agent's config. Compatibility helps, but check your hooks and plugins first.

A first-week plan

• Day one: install, run grok inspect, and ask it to explain the repo.
• Day two: write an AGENTS.md with build and test commands, then check it with grok inspect.
• Day three: turn on the workspace sandbox and add deny rules for rm -rf *.
• Day four: add one MCP server with grok mcp add and run grok mcp doctor.
• Day five: try /goal with a measurable finish line and a --budget cap.

Our take

This is an editorial reading of xAI's product page, pricing page and docs, not a hands-on test. The facts were checked on 31 October 2026 from the vendor's own pages.

The docs are unusually complete for a new tool. Permissions, sandbox, ZDR and managed config each get their own page, and the limits are written down, including the ones that make the product look worse, such as the macOS network gap. That honesty is useful when you are deciding what to trust.

The weak spot is the buying story. The plan ladder is shared with chat, images and an X account, usage is given as multiples, and the free route is described as "limited" without a number. If you want to know what a month of coding costs, you will have to try it and watch /usage.

Checklist

• Try it on the free route before paying
• Run grok inspect to see which rules, skills and MCP servers it loaded
• Turn on a sandbox profile and add deny rules
• Keep API-key runs in mind: they bill the API account, not the plan
• Set a --budget on long /goal runs
• Check /privacy and ask about ZDR before sending sensitive code
• Clean up worktrees with grok worktree gc
• Re-check pricing on x.ai the day you subscribe