Preface¶

Since 2026, the competitive focus of terminal coding Agents has shifted from “whose model is stronger” to “whether the Harness is transparent, auditable, and self-hostable”. OpenAI’s Codex CLI and anomalyco’s OpenCode have successively open-sourced their Agent runtimes under the Apache 2.0 / MIT licenses. On July 15, SpaceXAI (formerly xAI) followed suit, releasing Grok Build — the coding Agent behind the grok CLI and its full-screen TUI — under the Apache 2.0 license to the GitHub repository xai-org/grok-build.

The official announcement is available at Grok Build is Now Open Source. As of the end of July 2026, the repository has gained over 23,000 GitHub Stars, becoming another heavyweight open-source coding Agent Harness following Codex CLI and OpenCode.

This article is based on the official blog, GitHub README, and docs.x.ai/build documentation, sorting out what Grok Build has open-sourced, how its code is organized, and how to compile it locally and connect it to custom inference services.

What’s Open-Sourced¶

Grok Build is SpaceXAI’s terminal coding Agent. It understands codebases in project directories, edits files, executes Shell commands, retrieves web pages, and manages long-running tasks. It has three usage modes:
1. Interactive TUI: A full-screen, mouse-supported terminal interface;
2. Headless mode: Non-interactive execution via -p in scripts or CI/CD pipelines;
3. ACP Integration: Embedded into IDEs or custom applications via the Agent Client Protocol.

What is open-sourced this time is the Rust source code of the Harness and TUI, not the Grok 4.5 model weights. The official明确 that the repository includes the following modules:

The repository is synced regularly from SpaceXAI’s internal monorepo, and the SOURCE_REV file in the root directory records the corresponding monorepo commit SHA. The root Cargo.toml is a generated file, and you should modify the Cargo.toml under each crate for daily development.

License: The first-class code is licensed under Apache License 2.0; third-party implementations such as Codex and OpenCode referenced in third_party/ and tool crates retain their original licenses, see THIRD-PARTY-NOTICES for details.

Contribution Policy: The repository is a read-only mirror, external PRs are not accepted (see CONTRIBUTING.md). You can fork, modify, and commercially use the code, but you cannot merge changes upstream.

Code Architecture Overview¶

The README provides a clear crate hierarchy for reading the source code on demand:

If you want to audit “how the Agent decides which command to execute”, read xai-grok-shell and xai-grok-tools first; if you are concerned about the interactive experience, look at xai-grok-pager.

Agent Loop and Tool Layer¶

Grok Build’s Agent loop follows the common ReAct pattern: the model outputs structured tool calls → the Harness executes them in the sandbox/workspace → the results are injected back into the context → reasoning continues.

The tool crate (xai-grok-tools) implements the core capabilities of a coding Agent: file reading/writing and diffing, codebase search, terminal command execution, web page retrieval, etc. The official note in THIRD_PARTY_NOTICES.md that some tool implementations reference or port code from openai/codex and sst/opencode, which is consistent with the current trend of mutual reference in the open-source coding Agent ecosystem.

The workspace crate (xai-grok-workspace) is responsible for interacting with the real file system, version control, and execution checkpoints, and is the key entry point for understanding “how Agent changes are saved and how to roll back”.

Full-Screen TUI and Headless Mode¶

The TUI crate provides scrollback, slash commands, plan review, and inline diff viewers, and supports mouse interaction. The user guide is located at crates/codegen/xai-grok-pager/docs/user-guide/ in the repository, covering shortcuts, themes, configuration, etc.

Headless mode is suitable for automation scenarios:

cd your-project
grok -p "Explain this codebase"
grok -p "Explain the architecture" --output-format streaming-json

The first time you start the TUI, a browser will open for authentication; if you have no graphical environment, you can set the API Key:

export XAI_API_KEY="xai-..."
grok

One-click installation of pre-compiled binaries (macOS / Linux / Windows):

curl -fsSL https://x.ai/cli/install.sh | bash   # macOS / Linux
irm https://x.ai/cli/install.ps1 | iex          # Windows PowerShell
grok --version

Extension System: Skills, Plugins, Hooks and MCP¶

Grok Build’s extension capabilities are similar to the Skills / MCP ideas of products such as Claude Code and Cursor, but the source code is now fully readable.
- Skills / Plugins / Marketplaces: Load extensions by directory or marketplace configuration to expand Agent behavior;
- Hooks: Can be defined in config.toml to intervene in specific lifecycle stages;
- MCP Servers: Mount external tools and data sources via the Model Context Protocol;
- Subagents: Support multi-Agent collaboration.

To debug extension loading, use:

grok inspect

This command will list the configuration sources, instructions, skills, plugins, hooks, and MCP servers discovered in the current directory.

Agent Client Protocol (ACP) Integration¶

If you want to embed Grok Build into an IDE or self-developed application instead of manually chatting in the terminal, you should use the Agent Client Protocol. Grok implements ACP via JSON-RPC over stdio:

grok agent stdio

The typical handshake process (see Headless & Scripting documentation for details):
1. Send initialize to negotiate the protocol version and client capabilities;
2. Select an authentication method based on the returned authMethods (such as cached_token or xai.api_key) and send authenticate;
3. Call session/new to create a session, then issue tasks via session/prompt;
4. Assistant text and tool lifecycle events are returned in a stream via session/update notifications.

The compatible clients listed in the official documentation include Zed, Neovim (CodeCompanion, avante.nvim), etc. The community has already developed a Vercel AI SDK Provider based on ACP (ben-vargas/ai-sdk-provider-grok-build), and projects such as Multica have taken grok agent stdio as a first-class runtime.

Compared with grok -p --output-format streaming-json, ACP can expose the complete tool call lifecycle and MCP configuration, making it more suitable for IDE-level integration.

Local Compilation and Custom Models¶

Since open-sourcing, Grok Build has emphasized local-first: compile the Harness yourself, point the base_url in config.toml to your own inference endpoint, and you can run the Agent framework without relying on xAI’s cloud API (you still need to provide the model yourself).

Build from Source Code¶

Dependencies:
- Rust: The version is locked by rust-toolchain.toml, and rustup will automatically install it during the first build;
- DotSlash: Required for Hermetic toolchains (such as bin/protoc), run cargo install dotslash and ensure it is in the PATH;
- protoc: Required for Proto code generation.

git clone https://github.com/xai-org/grok-build.git
cd grok-build
cargo run -p xai-grok-pager-bin              # Build and start the TUI
cargo build -p xai-grok-pager-bin --release  # Release binary
cargo check -p xai-grok-pager-bin            # Quick validation

The output product is named xai-grok-pager; the official installation package symlinks it to grok.

For development, it is recommended to operate on a single crate to avoid compiling the entire workspace:

cargo check -p xai-grok-config
cargo test -p xai-grok-config
cargo clippy -p xai-grok-shell

Custom Model Configuration¶

The user-level configuration file path is ~/.grok/config.toml (Windows: %USERPROFILE%\.grok\config.toml).

[model.my-model]
model = "model-id"
base_url = "https://api.example.com/v1"
name = "Display Name"
env_key = "API_KEY"

[models]
default = "my-model"

After updating the configuration, specify the model in Headless mode:

grok -p "Hello" -m my-model

You can switch models in the TUI with /model <name>. If you still use xAI’s official models, the underlying model is grok-4.5, and you can also call it directly via the xAI API:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "input": "Fix this function and explain the bug: function median(a){a.sort();return a[a.length/2]}"
  }'

Horizontal Comparison with Codex CLI and OpenCode¶

The differentiator of Grok Build lies in: the Harness is fully open-source and model-agnostic, but the repository is a read-only sync, and the community cannot directly contribute to the official mainline; the tool layer also transparently references implementations from Codex / OpenCode, making it suitable as a reference sample for “studying top-tier Agent design” rather than an upstream project expecting community co-construction.

How Developers Can Use It¶

Combined with the official documentation and repository structure, several typical use cases are as follows:
1. Audit before deployment
Before enabling the Agent in a regulated repository, read xai-grok-tools and sandbox-related crates to confirm that the command execution boundary and permission model meet internal control requirements.

2. Fork the internal Harness
Apache 2.0 allows modification and redistribution. You can fork the code within your enterprise to customize the tool whitelist, access internal MCP, replace the default model endpoint; no need to wait for upstream merges.

3. Offline / air-gapped environments
Compile the binary locally, point base_url to the intranet inference service, skip api.x.ai, and only use the open-source Harness to orchestrate your own models.

4. CI pipelines
Headless mode with streaming-json output can embed tasks such as code review and architecture description into pipelines like GitHub Actions.

5. IDE / platform integration
Use grok agent stdio via ACP to get streaming tool call feedback in Zed, Neovim, or self-developed clients, which is more suitable for interactive editor scenarios than plain text Headless output.

Summary¶

xAI’s open-sourcing of Grok Build essentially makes public the “operating system layer” of coding Agents — loop scheduling, tool execution, TUI, extension loading. The grok-4.5 model is still used via API or subscription, but the Harness itself can now be compiled locally, connected to any OpenAI-compatible endpoint, and integrated into existing developer toolchains via ACP / MCP.

For developers who care about Agent engineering rather than a single model, the value of this Rust codebase lies in: you can directly read how context is assembled, how tool calls are dispatched, and how MCP is mounted — these details can usually only be guessed in closed-source CLIs. If you already use the grok command line, you may wish to compare it with the xai-org/grok-build source code to understand the implementation path behind each file edit and Shell execution.