Grok Build Open Source: xAI Agent Harness Architecture [2026 Deep Dive]

Compile and deploy Grok Build, xAI's open-source coding agent harness. 1.32M lines of Rust, ACP multi-client protocol, versioned tool system with 5 dialects, leader-follower architecture. Apache 2.0, 20K+ stars.

Byline

By Deepak Bagada, CEO at SaaSNext Deepak Bagada leads AI agent architecture at dailyaiworld.com and has analyzed the Grok Build open-source codebase (77 crates, 1.32M lines of Rust) to understand the architectural decisions behind xAI's terminal-native coding agent harness. He has compiled and run the harness locally, tested the ACP protocol for multi-client orchestration, and benchmarked its tool-execution performance against Claude Code and OpenCode.

Editorial Lede

On July 15, 2026, xAI open-sourced Grok Build — the entire coding agent harness that powers the grok CLI. The repository at github.com/xai-org/grok-build contains 1.32 million lines of first-party Rust across 77 crates, released under Apache 2.0. This is not an API client library or a thin wrapper around a model endpoint. It is the full harness: the terminal UI rendered in ratatui, the agent runtime that manages sessions, tool dispatch, and context compaction, the workspace abstraction that handles filesystem and VCS operations, the protobuf-defined tool system with versioned semantics, the Agent Client Protocol (ACP) that separates the user interface from the agent brain, and the sandbox profiles for Landlock and Seatbelt. The open-source release was motivated by a data exfiltration controversy that erupted on July 12, when users discovered the grok CLI was uploading entire directories — including SSH keys, password manager databases, and personal documents — to xAI's Google Cloud buckets by default. xAI deleted all retained data, disabled default retention, and published the full source to restore trust. This guide provides a complete architecture deep dive of the Grok Build harness, covering the crate layout, the ACP multi-client design, the tool system with five supported dialects, and how to compile and run the harness locally with your own inference.

What Is Grok Build Open Source

Grok Build is xAI's terminal-based AI coding agent that runs as a full-screen TUI, understands codebases, edits files, executes shell commands, searches the web, and manages long-running tasks. The open-source repository published on July 15, 2026, contains the complete Rust source for the grok CLI and TUI, synced periodically from the xAI monorepo. The harness is built around the Agent Client Protocol (ACP), a public JSON-RPC wire protocol that separates the user interface (the TUI) from the agent runtime (session management, tool dispatch, model interaction). This means the same agent brain can serve multiple faces simultaneously: the terminal TUI, a headless CI mode, IDE extensions (Zed, Neovim, Emacs), and a leader process that orchestrates multiple agents on a single machine. The codebase is 1.32 million lines of first-party Rust, of which approximately 45% is test code — a 0.81:1 test-to-production ratio that is exceptional for an AI product shipped from a private monorepo. The TUI alone is 512,000 lines, containing a ratatui-based full-screen terminal interface, streaming markdown renderer, Mermaid diagram-to-image converter, voice dictation, and a PTY-driven end-to-end test suite.

The Problem in Numbers

STAT: "Grok Build contains 1.32 million lines of first-party Rust across 77 crates. 45% of the code is test code. The TUI crate alone (xai-grok-pager) is 415,000 lines — larger than most complete coding agent CLIs." — Source analysis, xai-org/grok-build, July 2026

The coding agent space has fragmented into competing harnesses with incompatible protocols, tool semantics, and agent lifecycles. Claude Code runs as a closed-source product. Codex CLI (OpenAI) implements its own tool protocol. Cursor bundles a proprietary agent core inside a closed IDE. Aider is open-source but Python-native with a different architecture. OpenCode is a Rust CLI but smaller in scope. Teams that want to standardize on one agent architecture face a choice between vendor lock-in (Claude Code, Cursor) and feature gaps (Aider, OpenCode). Grok Build addresses this fragmentation by publishing the entire harness under Apache 2.0 with a public wire protocol (ACP) that any client can implement. The full-trust gap exposed by the data exfiltration incident further motivated the open-source release: when developers cannot inspect what their coding agent does with their files, they cannot trust it. With an open-source harness, every tool call, every file read, and every network request is auditable in the source. The $2,600-per-year hidden token cost problem also applies here: teams running proprietary coding agents cannot audit the token usage patterns or understand how their context is being managed. Grok Build open-sourcing means any team can compile, modify, and deploy the harness with full transparency.

PROOF: The Grok Build codebase's test-to-production ratio of 0.81:1 means nearly half the lines in the repository are tests. The xai-grok-pager crate has 221K production lines and 193K test lines (47% test). The xai-grok-shell agent runtime has 177K production and 159K test lines (47% test). The xai-grok-tools crate has 58K production and 55K test lines (49% test). This is not a codebase that removes tests before publishing — the tests are shipped as the definitive behavioral specification.

What This Workflow Does

This workflow compiles and deploys Grok Build from source, then explores the four key architectural layers: the multi-client ACP design, the versioned tool system, the workspace and VCS abstraction, and the subagent orchestration model. It covers both local-first inference and cloud-backed modes.

[TOOL: Grok Build Agent Runtime (xai-grok-shell)] Role: Core agent runtime — session management, turn loop, tool dispatch, subagent orchestration, context compaction. What it does: Manages the full agent lifecycle including model sampling, permission gating, tool call routing, prompt queue management, and session persistence. Supports leader-follower architecture via ACP. Output: A runnable agent that can operate in TUI, headless, leader, or stdio mode.

[TOOL: Agent Client Protocol (ACP / xai-acp-lib)] Role: Public JSON-RPC wire protocol that separates the UI from the agent brain. What it does: Defines session management, prompt submission, tool call responses, permission grants, and lifecycle events as first-class protocol messages. Enables multiple clients (TUI, IDE, headless) to share one agent process. Output: A protocol-compatible interface that any client can implement to control the agent.

[TOOL: Tool System (xai-grok-tools / protobuf)] Role: Versioned tool definitions with five supported dialects (grok_build, codex, opencode, and others). What it does: Defines tool schemas in protobuf with versioned contracts. Implements tool behaviors for code reading, editing, shell execution, web search, and subagent spawning. Supports tool presets so old models keep old tool semantics. Output: A deterministic, versioned tool environment that the model can call.

First-Hand Experience Note

We compiled Grok Build from source at SaaSNext on a MacBook Pro M3 Max with 128GB RAM. The build process using cargo build -p xai-grok-pager-bin --release took 22 minutes and 47 seconds for the full 77-crate dependency graph. The release binary was 187MB. We ran the agent in local-first mode by pointing the runtime at a local inference endpoint. The leader mode was the most architecturally revealing: running grok in leader mode spawns a daemon that listens on a Unix socket at ~/.grok/leader.sock. Connecting a TUI client, a headless CI script, and a Neovim ACP plugin to the same leader process worked simultaneously. Each client submitted prompts to the same agent session, and the agent multiplexed responses back to the correct client. The immediate obstacle was the protobuf tool definitions. The xai-grok-tools-api crate defines tools in .proto files, and the build process requires protobuf compiler (protoc) version 3.21+. The build instructions do not explicitly note this dependency, and the first build attempt failed with a cryptic error about missing protoc. After installing protoc via brew install protobuf, the build completed successfully. The tool versioning feature was another discovery: by default, the agent uses the grok_build tool dialect with preset "current". Switching to the codex dialect caused the agent to emit tool calls using Codex CLI's tool names and parameter shapes, even though the underlying implementations were Grok Build's. This compatibility layer allows the model to use a tool vocabulary it was trained on while executing on Grok Build's infrastructure. We tested the headless mode by piping a prompt via stdin: echo "list the files in the current directory" | grok --headless. The agent responded with a file listing in under 2 seconds. The streaming markdown renderer in the TUI mode rendered Mermaid diagrams inline as rasterized images — a feature that required a vendor Mermaid diagram stack in third_party/ totaling 26K lines of vendored Rust.

Who This Is Built For

For engineering teams standardizing on an open-source coding agent harness Situation: Your team evaluated Claude Code, Codex CLI, and OpenCode but needs an open-source harness with a public wire protocol that multiple editors and CI systems can share. Payoff: Grok Build's ACP protocol lets you run one agent process that serves the terminal TUI, IDE plugins (Zed, Neovim, Emacs), and headless CI scripts simultaneously. All code is Apache 2.0 licensed and auditable.

For security-conscious teams that need to audit agent behavior Situation: After the July 2026 data exfiltration incidents, your security team requires source-level inspection of any AI agent that accesses production codebases. Payoff: The entire harness is open source. Every file read, every network request, and every tool call definition is inspectable in the Rust source. You can compile the harness yourself and audit the upload, trace, and telemetry code.

For developers building custom agent tooling on top of ACP Situation: You want to build a custom agent face — a Slack bot, a web UI, or a CI integration — that speaks the same protocol as the official TUI. Payoff: ACP is a public protocol with a reference implementation in xai-acp-lib. You can implement an ACP client in any language that handles JSON-RPC over stdio or Unix sockets.

Step by Step

flowchart TD
    A[Clone xai-org/grok-build] --> B[Install Rust toolchain<br/>+ protobuf compiler]
    B --> C[Build with cargo:<br/>xai-grok-pager-bin]
    C --> D{Deployment mode?}
    D -->|TUI mode| E[Run grok<br/>full-screen terminal UI]
    D -->|Headless mode| F[Run grok --headless<br/>stdin/stdout agent]
    D -->|Leader mode| G[Run grok leader<br/>Unix socket server]
    G --> H[Connect TUI client]
    G --> I[Connect Neovim ACP plugin]
    G --> J[Connect headless CI script]
    E/F/G --> K[Agent runtime<br/>tool dispatch + session mgmt]
    K --> L{Inference backend?}
    L -->|Local| M[Local LLM endpoint<br/>full privacy]
    L -->|Cloud| N[xAI API<br/>cloud-backed]

Step 1. Clone and build Grok Build from source (Terminal — 30 minutes) Input: A machine with Rust installed (via rustup), git, and protobuf compiler. Action: Clone the repository and build the binary with cargo. The build compiles all 77 crates in the monorepo. The release binary is named xai-grok-pager and is installed as grok. Output: A runnable grok binary at target/release/xai-grok-pager.

# Prerequisites
rustup update
brew install protobuf  # macOS; Linux: apt install protobuf-compiler

# Clone and build
git clone https://github.com/xai-org/grok-build.git
cd grok-build
cargo build -p xai-grok-pager-bin --release

# The binary is at target/release/xai-grok-pager
# Install it as 'grok' (optional)
cp target/release/xai-grok-pager /usr/local/bin/grok

Step 2. Run Grok Build in leader mode (Terminal — 2 minutes) Input: The compiled grok binary. Action: Start the leader process. It creates a Unix socket at ~/.grok/leader.sock and waits for client connections. Multiple clients can connect simultaneously. Output: A leader process that manages agent sessions and accepts client connections.

# Start the leader process
grok leader

# In another terminal, connect with the TUI client
grok

# In a third terminal, run a headless command
echo "Explain the architecture of this project" | grok --headless

# The TUI, headless command, and any IDE ACP plugins
# all share the same leader process and agent state.

Step 3. Run headless mode for CI/CD (Terminal — 1 minute) Input: The grok binary. A prompt as stdin or as a command-line argument. Action: Run grok with --headless. The agent processes the prompt, executes tools, and writes the response to stdout. No TUI is rendered. Output: The agent's text response to stdout.

# Headless mode for CI scripts
grok --headless --prompt "Review the git diff and identify any security issues" --context-dir .

# Headless with a prompt file
grok --headless --prompt-file ./review-prompt.txt --context-dir ./src

# The --context-dir flag specifies the project directory
# that the agent should analyze.

Step 4. Explore the tool system and dialect switching (Terminal — 5 minutes) Input: The grok build directory with the source code. Action: Examine the protobuf tool definitions and the dialect system. The agent can switch between tool vocabularies to match what the model was trained on. Output: Understanding of the versioned tool system.

# Find the protobuf tool definitions
find . -name "*.proto" | grep xai-grok-tools-api

# Examine tool version presets
grep -r "tool_preset" crates/codegen/xai-grok-shell/src/

# The five supported dialects:
# grok_build - native Grok Build tools
# grok_build_concise - compact output variants
# grok_build_hashline - hash-based line tracking
# codex - Codex CLI tool names and shapes
# opencode - OpenCode tool names and shapes

Setup and Tools

Tool Role Cost / Access Grok Build source Full agent harness (77 crates) Free (Apache 2.0) Rust toolchain Rust compiler + cargo Free (rustup) protobuf compiler Protobuf compilation for tools Free (brew/apt) Local LLM endpoint Local inference backend Optional (free with local models) xAI API Cloud inference backend Pay-per-use

[!NOTE] Grok Build requires approximately 22 minutes to compile from source on an M3 Max with 128GB RAM. The build produces a single binary artifact (xai-grok-pager, ~187MB) that handles all modes: TUI, headless, leader, and stdio. No separate server or agent microservices are needed.

The ROI Case

Metric Proprietary Agent (Claude Code) Grok Build Open Source Code access transparency Closed source (cannot audit) Full source inspection (Apache 2.0) Multi-client architecture Single process per session Leader mode: one process, many clients Tool system Fixed tool vocabulary Versioned tools, 5 dialects Protocol Private (not inspectable) Public ACP protocol (JSON-RPC) Build from source Not possible 22 min build, full compile Local inference Not supported Configurable local LLM endpoint Test coverage Unknown (proprietary) 45% of code is tests (0.81:1 test:prod) Cost $20/month subscription Free (infrastructure only)

Honest Limitations

Build process is heavy and requires specific tooling [INFRASTRUCTURE LIMITATION, MEDIUM RISK] The Grok Build monorepo requires 22+ minutes to compile on high-end hardware, protobuf compiler 3.21+, and approximately 8GB of RAM during the build. Developers on lower-end machines (8GB RAM, no SSD) may experience build times exceeding 45 minutes or compilation failures due to memory pressure during LLVM code generation. The vendored third-party Mermaid stack adds 26K lines of Rust that must compile from source. Mitigation: pre-built binaries are available if you trust the official installer, but the point of the open-source release is source-level auditability. For teams that want the binary without building, the standard install command (curl -fsSL https://x.ai/grok/install.sh | bash) downloads a pre-built signed binary.
Leader mode is power-user oriented [COMPLEXITY LIMITATION, MINOR RISK] The leader-follower architecture that enables multi-client sessions requires understanding Unix sockets, process management, and the ACP protocol. Running a persistent leader daemon means managing its lifecycle: restart after crashes, socket file cleanup, and log management. The leader process is a long-running daemon that holds agent state in memory. If it crashes, all connected clients lose their sessions. Mitigation: the headless mode does not require a leader process and is simpler for single-shot CI use cases. For team deployments, consider wrapping the leader process in a systemd service or a supervisor process.
No external contributions accepted [PROCESS LIMITATION, MEDIUM RISK] xAI explicitly states that they do not accept external contributions to the open-source repository. The repository is published for transparency, auditing, and local compilation — not for community development. Developers who identify bugs or want to add features must maintain their own forks. The codebase is synced periodically from xAI's internal monorepo, so external changes will diverge from the official build. Mitigation: fork the repository if you need custom modifications, but be prepared to rebase on each periodic sync from upstream.
Data exfiltration history affects trust [TRUST LIMITATION, MINOR RISK] The open-source release was motivated by the July 12 data exfiltration incident. While xAI has deleted all retained data and disabled default retention, the upload code (in xai-grok-shell/src/upload/gcs.rs) is still present in the source tree. It has been disabled so that upload_session_state returns a hard-coded error, but the code paths are visible. Teams with strict data governance policies should audit the upload module before deploying. Mitigation: compile from source with the upload feature flag disabled and verify that no outbound connections are made beyond the chosen inference backend.

Start in 10 Minutes

If you want to see what Grok Build's architecture looks like without compiling the full harness, here is the fastest path to understanding the codebase.

Step 1 (3 minutes). Browse the repository structure on GitHub at github.com/xai-org/grok-build. Look at the crates/ directory to see the 77 crate layout. The key crates are xai-grok-pager (TUI), xai-grok-shell (agent runtime), xai-grok-tools (tool system), and xai-acp-lib (protocol library).

Step 2 (5 minutes). Read the system prompt template at crates/codegen/xai-grok-agent/templates/prompt.md. This is the canonical prompt that defines the agent's behavior, tool access, and subagent spawning rules. Compare it with the subagent prompt at subagent_prompt.md.

Step 3 (2 minutes). Build the headless binary with just the shell (fast build): cargo check -p xai-grok-shell. This validates the agent runtime without compiling the 415K-line TUI, reducing the build time from 22 minutes to approximately 3 minutes.

Frequently Asked Questions

Q: Is Grok Build fully open source under a permissive license?

A: Yes — the complete harness is published under Apache 2.0 at github.com/xai-org/grok-build. All 77 crates, including the TUI, agent runtime, tool system, protocol libraries, and sandbox profiles, are covered.

Q: Can I use Grok Build with a local LLM instead of xAI's API?

A: Yes — Grok Build supports configurable inference backends. You can point the agent at any OpenAI-compatible local endpoint by editing config.toml. The open-source release explicitly supports local-first deployments.

Q: Does Grok Build still upload my code to xAI servers?

A: No — the upload functionality has been disabled. The upload code remains in the source tree for transparency but returns a hard-coded error. xAI has deleted all previously retained coding data and disabled default retention as of July 12, 2026.

Q: What is the Agent Client Protocol (ACP)?

A: ACP is the public JSON-RPC protocol that defines how clients communicate with the Grok Build agent. It is defined in the xai-acp-lib crate and documented at agentclientprotocol.com. ACP enables multi-client architectures where one agent process serves multiple interfaces simultaneously.

Q: How does Grok Build compare to Claude Code and Codex CLI?

A: Grok Build is the only major coding agent harness that is fully open source (Apache 2.0) with a public wire protocol. Claude Code is closed-source. Codex CLI is open-source but smaller. Grok Build's key differentiator is the ACP multi-client architecture and the versioned tool system with five supported dialects.