Skip to main content

Inside Grok Build: Reading an Open Agent Harness

Advanced

On 14–16 July 2026, xAI published Grok Build — the coding agent behind its CLI — as a public Apache 2.0 repository at xai-org/grok-build. Not the weights. The harness: the agent loop, the tool implementations, the terminal UI, the extension system. It went to the front page of Hacker News within hours.

This is a rare artifact. Almost every serious coding agent — Claude Code, Cursor, Codex — ships as a binary or a bundle. Here, roughly 800,000 lines of production Rust are sitting in a repo you can read. That's worth more as a textbook than as a product.

This page is the practical read: what's actually in there, what the structure teaches you about building agents, and two things about this release that most of the coverage got backwards.

What you'll learn
  • Understand what was published and what wasn't — harness yes, weights no, development history no
  • Read the crate map as a checklist of what a production coding agent actually needs
  • Learn why Apache 2.0 here means source-available, not open-development — and why that distinction is load-bearing
  • See the data-collector code still present in the published tree, and what its constants confirm about the July exfil incident
  • Know what's genuinely reusable from this repo and what is a dead end

What was actually published​

The repository is 99%+ Rust, licensed Apache 2.0, and describes itself as a coding agent harness and TUI — fullscreen, mouse-interactive, extensible. It builds on macOS and Linux with a pinned Rust toolchain.

Three things it is not:

  • Not the model. Grok 4.5's weights are not here and are not open. The harness talks to a hosted endpoint. You can read every line of how the agent thinks about your codebase and still not run it without xAI's API.
  • Not a development history. The repo has two commits: Publish harness and TUI open-source, then Synced from monorepo. There's a SOURCE_REV file at the root containing a single internal revision hash. This is an export of a private monorepo, re-synced periodically — not a repository that was developed in public and not one you can archaeologize for design decisions.
  • Not open to you. CONTRIBUTING.md states plainly that the repository does not accept external pull requests or unsolicited patches, that xAI develops the software internally, and that the tree is published "for source transparency and local builds." GitHub issues are disabled at the repo level.

★ The distinction that matters: Apache 2.0 is a license, and it grants you real rights — read, fork, modify, ship derivatives. It says nothing about governance. Grok Build is source-available under an open-source license with a closed development model. You may fork it; you may not influence it. Read "open source" in the headlines as "you can read the source," because that is exactly and only what is on offer.

The crate map is the real lesson​

Ignore the marketing. The directory listing under crates/codegen/ is the most useful thing in the repo, because it is an honest inventory of what a shipping coding agent needs. A selection:

CrateWhat it tells you
xai-grok-agent, xai-grok-shellThe agent runtime and its entry points — interactive, stdio, headless
xai-grok-tools, xai-grok-tools-apiTool implementations, split from the tool interface — a real boundary
xai-grok-workspace, xai-fast-worktreeFilesystem, version control, execution, checkpoints — and fast git worktrees
xai-codebase-graphStructural understanding of a repo, not just grep
xai-grok-memoryMemory is a subsystem, not a prompt trick
xai-grok-mcpMCP is a first-class integration surface
xai-grok-hooks, xai-hooks-plugins-typesHooks and plugins have their own type layer
xai-grok-subagent-resolutionResolving which subagent handles what is hard enough to need its own crate
xai-token-estimationCounting tokens before you spend them
xai-hunk-trackerTracking diff hunks across an editing session
xai-grok-pager, xai-ratatui-inlineThe TUI — scrollback, prompts, modals, inline rendering
xai-acp-libAgent Client Protocol — editors embed the agent
xai-grok-telemetry, xai-mixpanelTelemetry and product analytics, as first-class crates
ptyctl, xai-tty-utils, xai-grok-crash-handlerTerminals are hostile and processes crash

Read that list again as a build plan. The naive mental model of a coding agent is "a loop that calls a model and runs tools." The actual decomposition includes a codebase graph, a memory subsystem, checkpointing, worktree management, hunk tracking, subagent resolution, token estimation, crash handling and a PTY control layer — before you write a single prompt.

★ The scale check. Simon Willison counted 844,530 lines of Rust in the tree, only ~3% of it vendored dependencies, and noted that OpenAI's Codex sits at roughly 950,933 lines. Two independent teams, converging near a million lines, for "a loop around an LLM." If your agent project feels like it's ballooning, this is the calibration: it is not you, and the hard part was never the loop.

There's also a xai-grok-mermaid crate — a terminal renderer that draws Mermaid diagrams with Unicode box-drawing characters. It is not important. It is a nice reminder that shipping polish is a large fraction of any real agent.

The data-collector code is still in the tree​

This is where the repo stops being a textbook and starts being evidence.

In July 2026 a researcher's wire capture showed Grok Build uploading entire repositories — full git history, never-read files, .env contents — to a Google Cloud Storage bucket, through a channel unrelated to what the model read. AILmanac covers that incident and the general failure mode in What your agent uploads. xAI disabled the behavior server-side and said the retained data would be deleted.

The published source contains that machinery. Verifiable from the repo directly:

  • crates/codegen/xai-grok-shell/src/upload/gcs.rs exists.
  • crates/codegen/xai-file-utils/src/upload_config.rs defines DEDUP_GCS_PREFIX = "repo_changes_dedup".

That constant is the interesting one. The researcher's intercepted upload went to object paths of the form gs://grok-code-session-traces/repo_changes_dedup/v2/…. The path prefix captured on the wire is a named constant in xAI's own published source. The same file defines both ARCHIVE_SCHEMA_VERSION (v2) and ARCHIVE_SCHEMA_VERSION_V3 — meaning the archive format had been iterated to a third version. This was maintained infrastructure, not a stray debug path.

The module documentation in gcs.rs is blunter than any press statement. It refers to the upload helpers as "the data-collector helpers," and the file's entire reason for existing is an engineering fix: threading refresh-aware credentials through so that stale tokens stop causing POST /v1/storage 401s. Someone was debugging the reliability of the repository upload path as production work.

Simon Willison reports that the upload path is now disabled in the published tree, returning a hard-coded error. That is consistent with xAI's stated position, and we were not able to independently confirm the specific mechanism by code search — treat it as reported rather than verified here.

★ What to take from this. Not "xAI is uniquely bad" — the wider lesson from the security page stands: this class of channel exists in some form in many agents, and reading the source is the only way to know. Take instead the meta-point: this is what source transparency is actually for. You cannot audit a binary's data flows in an afternoon. You can grep a published tree for bucket_url in about ten seconds. The release is genuinely valuable precisely because it makes the uncomfortable parts greppable.

Check yourself

0/4
  1. xai-org/grok-build is Apache 2.0 licensed. What does that tell you about contributing a fix upstream?
  2. The repo has two commits and a root SOURCE_REV file containing one hash. What does that mean?
  3. Roughly how large is the Grok Build harness, and what's the comparable figure for OpenAI's Codex?
  4. What does the DEDUP_GCS_PREFIX constant in upload_config.rs confirm?

What's actually reusable​

Be honest about the constraints before you fork:

Guided walkthrough1 of 4
  1. The crate boundaries are the product of a well-funded team shipping to real users. That decomposition — tools split from tools-api, workspace from agent, subagent resolution as its own concern — is the transferable asset. Copying Rust out of it buys you far less than copying the shape.

If you want to explore the tree without building it:

Clone and map the crate structure

git clone --depth 1 https://github.com/xai-org/grok-build
cd grok-build

# The inventory of what a production coding agent needs
ls crates/codegen/

# Where does data leave the machine? Start here, not with the README.
grep -rn "bucket_url\|/v1/storage\|upload_bytes" crates/ --include=*.rs | head -30

# Which internal revision was this cut from?
cat SOURCE_REV

Where it sits next to what you know​

If you drive Claude Code, Grok Build is the same category of tool with its guts exposed — read it as a second opinion on problems you already have. Coding agent CLIs compared places it against the field, and Grok for Claude users covers the xAI ecosystem around it.

For the architecture ideas the crate map gestures at, see long-running agent harnesses and agent memory architectures — xai-grok-memory and xai-grok-subagent-resolution are one team's answers to exactly those problems.

And read What your agent uploads alongside this page. That one shows you how to catch a channel like this on the wire with mitmproxy and a canary repo. This one shows you what it looks like in the source. The two techniques together are the whole audit.

Sources & further reading​