Grok Build

2026-07-18 · page · source ↗ · source summary

SpaceXAI's terminal-based AI coding agent — a pure-Rust, ~80-crate monorepo (~1M+ lines) implementing a full TUI coding harness with subagent spawning, persistent memory, context compaction, hooks/plugins, MCP integration, and the Agent Client Protocol. Open-source as publication (no external contributions), synced periodically from the internal SpaceXAI monorepo. The largest production Rust coding agent in the open.

Architecture

Grok Build is a layered monorepo in three tiers:

Foundation (crates/common/): A formal JSON-RPC 2.0 tool protocol with capability negotiation (xai-tool-protocol), a unified streaming Tool trait with type erasure (xai-tool-runtime), a transport-agnostic compaction engine with three strategies (xai-grok-compaction), a mid-turn interjection buffer (xai-interjection-core), and a circuit breaker for tool calls (xai-circuit-breaker).

Product (crates/codegen/): 50+ crates forming the application. The key subsystems:

Vendored (third_party/): Complete Rust implementations of the Mermaid diagram stack — parser, graph layout (dagre), and SVG renderer — plus graph algorithm libraries. Eliminates the Node.js dependency that every other Mermaid integration carries.

Key Techniques

The Tool Streaming Contract

Every tool implements the Tool trait, whose execute method returns a ToolStream<T> with a structural invariant: zero or more Progress items (text chunks, content blocks, or custom payloads) followed by exactly one Terminal result. Two constructors — terminal_only(result) for blocking tools and with_progress(stream, future) for streaming tools — guarantee this shape at the type level. The ToolDyn blanket impl handles JSON deserialization of args and re-serialization of output, so tool authors never touch JSON manually.

Compat Tool-Name Mapping

Agent definitions written for Claude Code (e.g., tools: Read, Bash, Grep, Edit, Task, Skill, LSP) resolve to Grok's ToolKind enum via a centralized mapping in xai-grok-tools/src/tool_taxonomy.rs. Unrecognized entries cause the builder to fall back to the full toolset rather than silently stripping tools — a deliberate safety-over-restriction choice. MCP tools (mcp__* prefix) are always preserved. Subagent type directives use regex pattern Agent(type1, type2) to constrain which subagent types can be spawned.

Template Variable System

Tool descriptions use ${{ template.variables }} syntax resolved at finalize time by TemplateRenderer. This decouples description authoring from concrete naming: ${{ tools.by_kind.task }} resolves to the task tool's function name regardless of namespace, and ${{ params.task.subagent_type }} adapts to the parameter name the model actually sees. The task tool description is dynamically built from discovered subagents.

Dual Tool Architecture

Web search and X search can be sent as either hosted tools (native Responses API types executed server-side by the agentic sampler, skipping the tool-call round-trip) or function tools (local implementations executed client-side). The backend_search toggle is ANDed with per-model capability flags at request time, so the same agent definition works across models with different server-side search support.

Three Compaction Strategies, One Engine

The xai-grok-compaction crate defines three styles sharing a common trait seam (CompactionItem, CompactionSampler, ItemTokenCounter): - Full-replace (code_compaction): The entire conversation is summarized by a dedicated compaction model. Used by Grok Build. Includes degeneracy detection and failure classification. - Tail-keep (intra_compaction): Recent turns preserved, older ones summarized. Used by Grok Chat's per-step pass. - Between-turn (inter_compaction): Chunked summarization between conversation turns.

Interjection Buffer

When a user sends a message while the agent is mid-turn, it goes into an InterjectionBuffer (EventQueue<PendingInterjection>). At the next safe drain point, drain_formatted() wraps each entry as a synthetic user message with the framing "The user sent a message while you were working." Entries are FIFO, one per message, never merged. This is a small crate (320 lines) but solves a real problem that most agent frameworks handle ad hoc.

Actor-Based Conversation State

ChatStateActor owns the full conversation in a dedicated tokio task. All access goes through ChatStateHandle (command + oneshot). This eliminates locks on the conversation vector — only one task ever touches it. Events are emitted on state changes for observers (TUI, logging, telemetry). The pattern is the same one used by xai-hunk-tracker.

Design Decisions

Rust all the way down. Unlike every other major coding agent — Claude Code (TypeScript), Codex (TypeScript), Pi/omp (TypeScript+Bun+Rust N-API), OpenHands/DeerFlow (Python), OpenMonoAgent (C#) — Grok Build is pure Rust from TUI to tool implementations. This trades slower development iteration for: no GC pauses during tool execution, single-binary distribution with jemalloc, and zero runtime dependencies.

TUI-first, not CLI-first. The primary interface is the 425K-line pager, with headless mode, stdio, and ACP as secondary delivery modes. This is the inverse of most coding agents, which are CLI-first with optional TUI. The TUI investment includes scrollback, modals, theming, and rendering subsystems.

Open source as publication, not collaboration. External contributions are not accepted. The repo is a periodic snapshot from the internal monorepo, recorded by SOURCE_REV. This is the same model as SQLite, Sentry, and Meta's Llama — the code is public but the development process is not.

Generated workspace root. The root Cargo.toml (workspace members, dependency versions, lints, profiles) is generated and treated as read-only. Per-crate Cargo.toml files are the canonical dependency declarations. This is unusual at this scale and reflects the monorepo sync workflow.

Dedicated compaction model. Rather than using the main conversation model for summarization, Grok Build can route compaction to a separate model. This avoids the failure mode where a degraded conversation model also degrades its own compaction.

Enterprise policy support. The config system supports Ed25519-signed requirements files and macOS MDM managed preferences — unusual features for a developer CLI tool that indicate SpaceXAI's enterprise ambitions.

Vendored Mermaid stack. Instead of shelling out to Node.js mermaid-cli (the standard approach), Grok Build contains complete Rust implementations of the Mermaid parser, dagre layout engine, and SVG renderer. Zero Node.js dependency.

Fail-open tool allowlists. If a tools: allowlist contains entries that can't be mapped to any known tool, Grok Build falls back to the full toolset rather than leaving the agent crippled. MCP access is always preserved. The philosophy: an overly restrictive allowlist is more dangerous than an overly permissive one.

Comparison Notes

Grok Build is the most architecturally ambitious open-source coding agent. Compared to peers:

What distinguishes Grok Build architecturally is the formal protocol layer (tool registration, capability negotiation, JSON-RPC envelope) and the three-strategy compaction engine shared across product lines — both suggest an architecture designed for a platform, not a single product.

Sources: raw/grok-build Last updated: 2026-07-18 Tags: #tool #project #agents #coding-agent #rust #TUI #terminal #MCP