Grok Build

Grok Build is the youngest tool in this module. It was announced on May 25, 2026 as an early beta, and its source code went public on July 15, 2026. That is not much track record, so nothing below comes from a third-party blog. If the official pages did not say it, the lesson does not say it either. One naming note: as of September 2026 the company's own website, docs, and GitHub repository print the name SpaceXAI. This lesson says xAI, and you will see both.

What it is

Grok Build is a coding agent that runs in your terminal. A coding agent is a program that takes a plain-English request, reads your files, edits them, runs commands, and reports back, in a loop, until the job is done or it needs you. The idea is the same one the Claude Code and Codex lesson introduced. xAI's own description is a full-screen text interface that understands your codebase, edits files, executes shell commands, searches the web, and manages long-running tasks.

It runs three ways. Interactively, where you type and it works in front of you. Headlessly, where you pass a prompt with the -p flag and it runs with no interface, which is how you put it in a script. And embedded, through the Agent Client Protocol, usually shortened to ACP, a standard that lets another program host the agent in its own window.

The name is doing triple duty, and that trips people up. "Grok Build" is the terminal agent this lesson covers. "Grok Build 0.1" is a model, announced May 29, 2026, sold through the xAI API. And since August 19, 2026 the Grok chat app on web and mobile has a feature also called Grok Build that turns a description into an app inside the chat. When you read a headline, check which of the three it means.

License and code: the repository at github.com/xai-org/grok-build is under the Apache License 2.0 for xAI's own code, with vendored third-party pieces under their original licenses. The README credits ports from Codex and OpenCode. As of the verification date the repository has no tagged releases, so there is no version number to quote. The installed program reports its own with grok version.

Who gets it and how

The announcement page, which still reads "early beta" as of 2026-09-17, says the terminal agent is available to all SuperGrok and X Premium Plus subscribers. If you already pay for either one, Grok Build is included. The docs also show a second path: set an XAI_API_KEY environment variable and it runs against your API account instead, which is pay-per-token and meant for servers and scripts. No prices appear on any of the pages this lesson was checked against, so none appear here.

Install is one line on a Mac or Linux machine:

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

Windows has a matching PowerShell one-liner on the same docs page. On first launch it opens a browser to sign you in. After that you change into a project folder and type grok. That is the whole first run.

Two things to learn in the first ten minutes. First, Shift+Tab cycles the session mode. Plan mode means Grok can only edit its own plan file until you approve. Auto mode lets a classifier approve safe actions and still asks about risky ones. The third mode skips the prompts entirely, which you should not use until you have read the permission modes lesson and have git as your undo button. Second, grok inspect prints what the agent found in the current folder: rules files, skills, plugins, hooks, and MCP servers, with paths and token counts. Run it before you trust the agent with a new project.

The rules file, and why yours already works

A rules file is a Markdown file the agent reads at the start of every session so you do not repeat yourself. Grok Build reads the same file the rest of this module keeps coming back to: AGENTS.md. The docs list every name it accepts, and the list is generous. AGENTS.md, Agents.md, and AGENT.md. CLAUDE.md, Claude.md, and CLAUDE.local.md. And any Markdown file inside a .grok/rules/, .claude/rules/, or .cursor/rules/ folder.

Load order matters when two files disagree. Global rules in ~/.grok/ load first. Then every folder from the repository root down to the one you are working in, and the deeper file wins on a conflict. That is the same shape Claude Code and Codex use, which is exactly why the one AGENTS.md for every tool pattern holds. Write the rules once at the repository root: build command, test command, the "never touch these folders" list, house style. Codex and Grok Build read it directly, and the linked lesson covers the rest. You maintain one file.

Grok goes a step further on compatibility, and this is the most useful fact in the lesson if you already run Claude Code. The docs state that Grok is compatible with Claude Code with zero configuration. It reads Claude Code's instruction files, skills, plugins, and marketplaces alongside its own .grok/ folder. Skills are discovered from .grok/skills/, ~/.grok/skills/, and ~/.agents/skills/, each one a folder with a SKILL.md file, the same convention the Skills lesson taught. A grok import command pulls Claude Code sessions across. In practice a folder you set up for Claude Code is already set up for Grok Build. The exercise at the end tests that claim.

Settings live in TOML, a plain text format with sections in square brackets. User settings are in ~/.grok/config.toml, project settings in .grok/config.toml at the repository root, and the project file wins. That is where the default model and MCP servers are declared.

What is distinctive

Everything in this section is documented on docs.x.ai as of the verification date. Whether each feature is polished is a separate question, covered next.

• Worktrees as a first-class idea. A git worktree is a second checkout of the same repository in a separate folder, so two agents can edit at once without stepping on each other. Grok Build opens one with grok -w or grok --worktree=name, stores it under ~/.grok/worktrees/, and can fork a running session into one with /fork --worktree. You merge the result back with ordinary git. The announcement calls this deep worktree integration, and it is the feature xAI leads with.
• Subagents that can ask for their own worktree. A subagent is a child session with its own context that returns a summary to the parent when it finishes. Three built-in types ship: general-purpose, explore, and plan. Custom definitions live in .grok/agents/ or ~/.grok/agents/, managed with /config-agents. The docs say a subagent can request worktree isolation when the parent hands out parallel work. Compare the Claude Code version of the same idea.
• MCP servers with a familiar add command. MCP, the Model Context Protocol, is how you hand an agent a tool it did not ship with. grok mcp add name -- command adds a local server and --transport http adds a remote one, with --scope project writing to the project config instead of your home folder. Tools show up namespaced as server__tool. /mcps opens the management panel. If you have used the Claude Code add command, this will feel familiar.
• Plan mode with a plan file you approve. In plan mode the only file Grok may write is the session plan. You read it, then approve, then it executes. The transcript above shows the shape.
• Headless and hostable. The -p flag runs a single prompt with no interface, and --output-format streaming-json gives a script something to parse. grok agent stdio runs it as an ACP agent for another program to drive.

What is missing or immature, as of 2026-09-17

These are dated observations from the official pages, not verdicts. Each one could change with a release, and given the pace so far, several probably will. Recheck the docs before repeating any of them.

• The announcement still says early beta nearly four months after launch, and the repository shows no tagged releases. You cannot point at a version and say "this one is stable." Claude Code and Codex both publish numbered releases with changelogs you can read before upgrading.
• No named editor integration. The docs describe ACP support and the stdio command for it, but no page checked for this lesson lists an editor that hosts Grok Build. A separate xAI post covers a Grok subscription inside Kilo Code, which is a different product using Grok's models, not Grok Build. Codex and Claude Code both ship editor extensions. If you want the agent in a window next to your files, this is the gap to watch.
• Worktrees are not cleaned up for you. The docs are explicit that a worktree persists until you remove it, and that ending or deleting a session leaves the checkout in place. There is a grok worktree rm command and a grok worktree gc command with a max-age option. Budget disk space and a monthly tidy-up if you use this feature.
• Permissions are documented thinly. The settings page names the config files and the model keys, but as of the verification date it shows no concrete examples for permission rules, sandbox rules, or hooks the way the Claude Code settings and secrets lesson could. The modes exist. Fine-grained allow and deny lists are harder to find.
• A tool that reads everything. Reading CLAUDE.md, .cursor/rules, and .claude/rules alongside its own files is a convenience, and also a surface. If a colleague's Cursor rule says "always use framework X," Grok will follow it in a project where you never intended that. Run grok inspect and read the whole list.

Where it fits for a small business owner

If you pay for X Premium Plus because you post there, or for SuperGrok because you like the chat app, you already own a terminal coding agent you have probably never opened. That changes the math. Claude Code and Codex each need their own subscription or API spend. Grok Build comes with a bill you are already paying, and the install is one line.

What that buys a landscaper in Washington or a tint shop in St. George is the same thing the other agents buy: a way to say "add a contact form to my site" and get a draft with the changes shown before they land. The agent in your business, safely lesson applies word for word. Start in plan mode. Keep the work in a git repository so every change is reversible. Do not use the always-approve mode on a folder with customer data in it.

The honest summary is that Grok Build is a second agent, not a first one, for most readers of this module. Use it for a second opinion on a plan, for a parallel task in its own worktree, or because it came with a subscription you already have. Without numbered releases an update can change its behavior with no changelog to read first, so do not make it the only agent on work that has to be right the first time. Keep the rules in one AGENTS.md so switching costs nothing, and let the next lesson's decision table settle which agent gets the first seat.

Try this yourself

Take a folder you already use with Claude Code and ask both agents the same question. If you do not have one, make a folder with a short AGENTS.md that lists three rules and one HTML file.

1. Install with the one-line command above, then run grok version to confirm it is on your path.
2. Change into the folder and run grok inspect. Note every rules file it lists, with the path and token count. If a .cursor/rules/ or CLAUDE.md shows up that you forgot about, that is the point of the exercise.
3. Start grok, press Shift+Tab until plan mode is active, and paste the prompt below.
4. Open Claude Code in the same folder, plan mode there too, and paste the same prompt.
5. Compare the two answers line by line. They should name the same files. Where they differ, one of them is reading a file the other does not, and you want to know which.

Before doing anything, explain the rules you loaded for this folder. List every instruction file by path, summarize what each one tells you to do, and say which file wins if two of them disagree. Do not edit anything.

If both describe the file the same way, your one-file setup works and you can pick either tool by price. If they do not, fix the file before you give either one a real job.