Grok Build is SpaceXAI’s terminal coding agent, and using it well is mostly a matter of knowing which parts to switch on before you let it near a repository. It installs with a single line, authenticates through your X account, runs on Grok 4.6 by default, and will read files, edit them, run shell commands and open pull requests on your behalf. That is a lot of authority to hand a large language model on day one, so this guide walks the setup in the order that keeps you in control.
There is a second reason to be deliberate here. In July 2026 an independent wire-level analysis showed the tool uploading entire git repositories to cloud storage in the background, at roughly 27,800 times the volume the model actually consumed. SpaceXAI open-sourced the whole codebase days later. That history is not a reason to avoid the tool, but it is a reason to configure it rather than accept the defaults, and the last third of this article deals with it directly.
What follows is a practical sequence: prerequisites, install, first session, plan mode, subagents, extensions, headless and editor use, model selection, cost, and the limits worth respecting. If you are folding agentic coding into an AI strategy rather than trying it on a side project, the cost and privacy sections are the ones that will decide the answer.
Table of contents
- What Grok Build Is, and Which Grok Build You Mean
- What You Need Before You Install Grok Build
- How to Install Grok Build on Windows, macOS and Linux
- Your First Grok Build Session, Step by Step
- Using Plan Mode in Grok Build Before It Touches Your Code
- How Grok Build Subagents Split a Large Task
- Extending Grok Build with Skills, Plugins and MCP Servers
- Running Grok Build Headless, in CI and Inside Your Editor
- Which Model Grok Build Runs, and How to Change It
- What Grok Build Costs on Each Plan
- The Grok Build Privacy Incident and What It Changed
- Practical Limits and Mistakes to Avoid with Grok Build
- Grok Build FAQ
- References and Further Reading
What Grok Build Is, and Which Grok Build You Mean
SpaceXAI has attached the name to two different products, and confusing them is the most common early mistake. This guide covers the terminal agent.
| Aspect | Grok Build (terminal agent) | Build Mode (in the Grok app) |
|---|---|---|
| Where it runs | Your machine, your shell | Inside a Grok chat thread |
| What it touches | Real files, real commands | A hosted preview app |
| Launched | Early beta 14 May 2026 | 28 July 2026 |
| Output | Commits in your repository | A grok.me link or custom domain |
| Source code | Apache 2.0 on GitHub | Closed |
| Audience | Developers with a codebase | Anyone describing an app |
The terminal agent is the one this guide covers
Grok Build in the terminal is a fullscreen TUI with mouse support. It understands a codebase, edits files, executes shell commands, searches the web and manages long-running tasks. SpaceXAI describes it as “a powerful and extensible coding agent” reachable through the interactive interface, headless scripts, or the Agent Client Protocol from inside another application.
Build Mode is the in-chat one
Build Mode is the vibe-coding feature. You describe a website, dashboard, game or planner in a Grok conversation and a working version renders live in the thread. It launched gated to SuperGrok Heavy on 28 July 2026 and reached every plan, including Free, by 25 August 2026. It publishes to a grok.me subdomain. It is not the subject of this article.
Why the naming overlap matters
Search results for Grok Build mix the two constantly, so installation instructions and pricing claims from one frequently get applied to the other. If an article tells you Grok Build needs no install, it is describing Build Mode. If it gives you a curl command, it is describing the agent.
What You Need Before You Install Grok Build
Three prerequisites, and only one of them is technical.
An X account or an API key
Launching the tool for the first time opens a browser and authenticates against your X account. On a headless box, a CI runner or a container with no browser, export an API key instead:
export XAI_API_KEY="xai-..."
Set it before starting the agent and the browser step is skipped entirely.
A plan that will not run dry
Grok Build is usable on the Free tier, but the token allowance depletes quickly under agentic work — an agent that reads twenty files to answer one question spends far more than a chat turn. SuperGrok at $30 a month and SuperGrok Heavy at $300 a month raise the ceiling. Allowances reset weekly, not daily, which changes how you pace a big refactor.
A repository you are allowed to send to a vendor
This is the prerequisite people skip. The agent is a cloud product: the model runs on SpaceXAI infrastructure, so your code leaves your machine. If the repository contains client data, regulated material or credentials, that decision belongs with whoever owns your data protection policy and with whoever answers for cybersecurity, not with the developer running the install script.
How to Install Grok Build on Windows, macOS and Linux
Installation is one line on every supported platform.
| Platform | Shell | Command |
|---|---|---|
| macOS | Terminal / zsh | curl -fsSL https://x.ai/cli/install.sh | bash |
| Linux | bash | curl -fsSL https://x.ai/cli/install.sh | bash |
| Windows | PowerShell | irm https://x.ai/cli/install.ps1 | iex |
| Windows | Git Bash | curl -fsSL https://x.ai/cli/install.sh | bash |
The one-line installers
Piping a remote script into a shell is convenient and is exactly the pattern security teams ask you not to normalise. Fetch the script, read it, then run it — curl -fsSL https://x.ai/cli/install.sh -o install.sh followed by a look at the file costs thirty seconds. The same caution applies to the PowerShell variant.
Building Grok Build from source
Because the project is open source under Apache 2.0, you can compile it yourself. The repository is Rust, pinned through rust-toolchain.toml, and needs the DotSlash tool downloader plus protoc for proto generation. Build hosts are macOS or Linux; Windows is best-effort. cargo build -p xai-grok-pager-bin --release produces the binary, and cargo run -p xai-grok-pager-bin launches the interface directly.
Verifying the install
Open a new shell so the updated PATH is picked up, then run grok. First launch triggers authentication. The repository has passed 26,500 stars and 5,000 forks, so if a command in an older tutorial fails, check the current docs rather than assuming a broken install — the tool has moved quickly.
Your First Grok Build Session, Step by Step
Resist the temptation to open with a refactor. The first session should teach you how the agent behaves on your codebase.
Change into the project directory first
The agent takes its working context from the directory you launch it in. cd into the repository root, then type grok. Starting it in your home directory and asking it to find the project wastes tokens and gives it a far wider blast radius than you want.
Start with a read-only question
Ask it to explain something. “Walk me through how authentication works in this codebase” produces a useful answer, costs little, and shows you how the agent navigates your file layout. Engadget’s walkthrough makes the same recommendation: understand the codebase reading before you ask for edits.
Then ask for one small change
Pick a change you could review in two minutes — a bug fix with a known reproduction, a missing test, a dependency bump. Read the diff properly. What you are calibrating is not whether the agent can write code; it is whether it writes code the way your team writes code, which is a question about your conventions, not its capability.
Using Plan Mode in Grok Build Before It Touches Your Code
Plan mode is the single most valuable habit for anyone using this tool on real work, and it is the one SpaceXAI’s own product page leads with.
Every edit is blocked until you approve
Start a complex task in plan mode and the agent produces a plan.md in a dedicated viewer instead of editing anything. A migration request such as “move auth from sessions to JWT with token rotation” yields a bottom line, an approach, and a numbered step list. Nothing is written to disk while you read it.
Approve, comment, or rewrite
The viewer offers three responses: approve the plan wholesale, comment on individual steps, or rewrite it entirely. Commenting is the underused option — correcting step four before execution is dramatically cheaper than reverting step four afterwards, in both tokens and review time.
The Q&A step catches ambiguity early
When a request is underspecified, Grok Build asks a short multiple-choice question rather than guessing. Design direction, framework, schema shape — you pick, and the answer flows straight into the plan. This is the mechanism that prevents the agent from confidently building the wrong thing, so answer the questions rather than skipping them.
Every approved change shows up as a clean diff
Approval does not mean blind execution. Changes surface as diffs you review, which keeps the workflow compatible with normal code review rather than replacing it. Teams with mature DevOps practice should route agent output through exactly the same checks as human output.
How Grok Build Subagents Split a Large Task
Subagents are what separate the tool from a chat window with file access.
Each child runs with its own context window
Grok Build delegates larger tasks to specialised subagents that run in parallel, each with a separate context window. Exploring a checkout flow, the CI configuration, shared libraries, order services and a pricing engine happens simultaneously rather than sequentially, and the parent agent assembles the findings.
Worktrees keep parallel work apart
The agent supports launching subagents in their own git worktrees. That matters because parallel writes to one working tree produce conflicts that are tedious to unpick. Give each subagent its own worktree and independent work stays independent.
When not to fan out
Parallelism multiplies token spend. Five subagents exploring five subsystems cost roughly five times one, and on the Free tier that is how an allowance disappears in an afternoon. Fan out for genuine breadth — an unfamiliar monorepo, a cross-cutting audit — not for a task a single agent would finish in one pass.
Extending Grok Build with Skills, Plugins and MCP Servers
Extensibility is where the tool becomes yours rather than generic.
Skills and the /skillify command
Skills adapt the agent to your workflows. They are auto-invoked when a task matches, or called by name. The useful trick is /skillify, which captures any session as a new skill — so a sequence you worked out once becomes a reusable capability instead of something you re-explain every week.
Plugins and marketplaces
Plugins bundle skills, agents, hooks and MCP servers behind a single install, distributed through a marketplace or self-hosted from any git repository. For a team, this is how you stop everyone configuring the agent differently: one internal marketplace entry, one install command, consistent behaviour.
MCP servers and grok inspect
Model Context Protocol servers work out of the box, and grok inspect discovers what is available. Linear, Sentry, Postgres and browser automation all connect through MCP, which is what lets the agent read a ticket, reproduce an error and check a database without you pasting context between windows.
AGENTS.md and hooks
AGENTS.md in the repository root, plus hooks, work without configuration. Put your conventions in that file — branch naming, test commands, formatting rules, directories that are off limits — and you stop repeating them in every prompt. It is the cheapest quality improvement available.
Running Grok Build Headless, in CI and Inside Your Editor
Interactive use is only one of three modes.
Headless with the -p flag
grok -p "Explain this codebase" runs a single prompt without the TUI. This is the mode for scripts, cron jobs and CI steps — anywhere a fullscreen terminal interface would be meaningless.
Streaming JSON output
Add --output-format streaming-json and the response arrives as structured events you can parse. That turns Grok Build into a component in a pipeline rather than a tool a human watches, which is the pattern behind most useful intelligent automation around coding agents.
ACP for editors
The Agent Client Protocol exposes the agent to other applications, so editors that speak ACP can drive it without a terminal. If your team lives in an IDE, this is the integration path rather than asking everyone to change how they work.
Which Model Grok Build Runs, and How to Change It
The default is current, and the override is a config file away.
Grok 4.6 is the default
Grok 4.6 shipped on 12 August 2026 and powers the agent. SpaceXAI offered 2x included usage through Grok Build during the model’s first release week, and positions it for extended agentic tasks — turning a product concept into a working application across many iterations.
| Benchmark | Grok 4.6 score | What it measures |
|---|---|---|
| AA Intelligence Index | 61 | Composite capability, tied with GPT-5.6 Sol |
| CursorBench v3.2 | 69.9% | Editor-grounded coding tasks |
| DeepSWE v1.1 | 65.9% | Software engineering task completion |
| FrontierCode v1.1 | 61.3% | Harder frontier coding problems |
The config.toml route to other models
Point Grok Build at a different model through ~/.grok/config.toml, or %USERPROFILE%\.grok\config.toml on Windows. Each entry takes a model ID, a base URL, a display name and the name of the environment variable holding the API key. /model <name> switches between configured models mid-session.
What the benchmarks actually say
Four scores in the sixties, and a composite index tied with a rival rather than ahead of it. That is a competent frontier model, not a decisive lead. Choose the agent for its harness — plan mode, subagents, MCP, open source — because the model layer is close enough that it will not be the deciding factor.
What Grok Build Costs on Each Plan
Two separate meters run here, and mixing them up produces very wrong budgets.
| Plan | Price | Token allowance | Best for |
|---|---|---|---|
| Free | $0 | Limited, depletes quickly | Evaluating the tool |
| SuperGrok | $30 / month | Higher allocation | Regular individual use |
| SuperGrok Heavy | $300 / month | Highest threshold | Daily agentic workloads |
| API (Grok 4.6) | $2 in / $6 out per M tokens | Metered, no cap | Pipelines and CI |
The subscription meter
Paid tiers draw from one shared weekly pool spread across Chat, Imagine, Voice and Build rather than separate per-feature quotas. SpaceXAI does not publish a fixed request count that holds across every tier and task type, which makes capacity planning awkward — you learn your own ceiling by hitting it.
The API meter
Grok 4.6 starts at $2 per million input tokens and $6 per million output tokens, with a faster variant at double the price. Running Grok Build headless against an API key bills this way instead, and for CI usage that is usually the cheaper and more predictable route.
Budget for the agent, not the seat
The mistake is treating this as a per-seat licence. Agentic coding consumes tokens in proportion to how much code the agent reads, and a subagent fan-out across a large monorepo is expensive by design. Track spend per developer for a month before committing to a tier.
The Grok Build Privacy Incident and What It Changed
This is the part a setup guide has to cover honestly, because it changes how you configure the tool.
What the wire capture showed
On 10 July 2026 a researcher working under the handle cereblab published a wire-level network analysis of Grok Build CLI v0.2.93. Against a 12 GB repository, the model conversation channel carried about 192 KB of context — while a separate background process uploaded 5.10 GB, a full git bundle including history and deleted secrets, to Google Cloud Storage. The storage upload was roughly 27,800 times the conversation volume.
The privacy toggle did not stop it
The researcher repeated the test with the “Improve the model” setting disabled. The git bundle uploaded anyway, and the server’s settings endpoint still reported trace upload as enabled. In another run the agent was told to reply OK and read no files; it complied on screen, and the repository uploaded regardless. The /privacy command was never designed to govern repository uploads.
What open-sourcing does and does not fix
SpaceXAI published the full codebase under Apache 2.0 on 15 July 2026 and reset usage limits, saying that “publishing the code is the most direct way to build toward a robust and reliable harness.” The repository exposes the agent loop, the tools, the terminal UI and the extension surface, and it makes local-first operation with custom inference possible. What it does not do is retroactively unsend anything, and the company does not accept external contributions.
The configuration that follows from it
Treat any repository you point the agent at as disclosed to the vendor unless you have verified otherwise on the current version. Scrub credentials from history before first run rather than after, keep regulated codebases off the tool entirely, and if you need strong guarantees, use the open-source build with your own inference endpoint. Your IT security policy should name agentic CLI tools explicitly.
Practical Limits and Mistakes to Avoid with Grok Build
Four failure modes account for most bad first weeks.
Skipping plan mode on a large repository
Without plan mode the agent starts editing immediately, and on an unfamiliar codebase that means a wide diff you did not scope. Engadget’s guidance is blunt about this: use plan mode before major changes, both to prevent unintended modifications and to avoid excessive token consumption. Both halves of that sentence cost real money.
Pointing it at a repository you cannot share
Covered above, and worth repeating because it is irreversible. Nothing in the interface will stop you.
Treating the diff as reviewed
An approved plan and a clean diff are not a code review. The agent optimises for a plausible change that satisfies the request; it does not know your production incident history. Route agent commits through the same review, tests and staging as anything else — this is the discipline that separates teams getting value from AI employees and autonomous AI agents from teams accumulating debt.
Assuming an older tutorial still applies
The tool moved from early beta in May 2026 to open source in July to a Grok 4.6 default in August. Slash commands, flags and config keys have shifted across that window. When something does not work, check the current documentation before debugging your environment.
Grok Build FAQ
Is Grok Build free to use?
Yes, on the Free tier, but the token allowance depletes quickly under agentic work. SuperGrok at $30 a month and SuperGrok Heavy at $300 a month raise the ceiling, and allowances reset weekly.
Does Grok Build run offline?
No. The default configuration sends work to Grok 4.6 running on SpaceXAI infrastructure. The open-source release makes a fully local-first setup possible with custom inference, but that is a deliberate configuration, not the out-of-the-box behaviour.
Which model does Grok Build use?
Grok 4.6 by default, released 12 August 2026. Other models can be configured in ~/.grok/config.toml with a model ID, base URL and API key variable, then selected with /model <name>.
Can Grok Build run in CI?
Yes. Use headless mode with grok -p "<prompt>", set XAI_API_KEY so no browser authentication is needed, and add --output-format streaming-json when a downstream step has to parse the result.
Is Grok Build safe to point at a private repository?
Only after you have satisfied yourself about what leaves the machine. The July 2026 analysis found entire git bundles uploading in the background regardless of the privacy setting, so scrub secrets from history first and keep regulated code off cloud-backed agents.
How does Grok Build differ from Build Mode?
Grok Build is a terminal agent that edits real files in your repository. Build Mode is an in-chat feature of the Grok app that generates a hosted app from a prompt and publishes it to a grok.me link. Different products, similar names.
References and Further Reading
How to use SpaceXAI’s Grok Build – Engadget
Grok Build product page – SpaceXAI
Grok Build overview – SpaceXAI developer documentation
Grok Build is Now Open Source – SpaceXAI
Introducing Grok 4.6 – SpaceXAI
Introducing Grok 4.5 – SpaceXAI
Grok Build CLI Caught Uploading Entire Repositories – The Agent Report
Researcher Confirms Privacy Mode Cannot Stop Repository Uploads – Security Online
Grok Build Privacy Controversy: Repository Data Uploads
Grok Build Shipped Entire Codebases to xAI Cloud – Tech Times
Grok Build: Free Access, App Creation, Publishing, Models and Current Limits
More AI coverage: explore Progressive Robot's AI Models, Tools & Releases hub — hands-on reviews, setup guides and benchmarks in one place.