Grok Build Is an Agent System, Not Just a Chat Window
Grok Build is a terminal-based AI coding agent: it reads a codebase, edits files, runs commands, searches for information, and keeps work going after a single command has finished. This chapter focuses on what kind of system makes those abilities possible. The practical goal is not to memorize Grok Build's commands, but to learn how to trace a request from an interface to a real side effect, and then ask who owned that action, what constrained it, and how its result became visible.
That framing matters because Grok Build can look like three different products. In its full-screen TUI, a user watches a conversation, tool calls, file changes, and task activity in one terminal view. In headless mode, a prompt becomes a command-line operation suitable for scripting or CI. Through the Agent Client Protocol, or ACP, an editor or another application can create sessions, send prompts, receive streamed updates, and handle permissions without rendering Grok Build's own interface. These are different ways to meet the agent, not three unrelated kinds of intelligence.
One agent, three ways to meet it
The TUI is the most visible form. It gives the user a scrollback containing prompts, answers, tool calls, search results, and inline file changes, plus a prompt area where the next request is composed. That arrangement makes the agent's activity inspectable while it is happening. A command is not merely a hidden operation whose final answer appears later; the terminal can show that a command is running, that a file was edited, or that a task is waiting.
Headless mode changes the relationship, not the underlying purpose. A command such as grok -p accepts one prompt and exits when the turn is complete. Its plain-text output is useful for a person, while JSON and newline-delimited event streams are useful to another program. The machine-readable forms can expose response text, stop reasons, session identifiers, tool-call updates, plans, usage information, and errors. A script can therefore treat Grok Build as a component in a larger workflow, while still retaining a handle for resuming the session later.
ACP goes one step further. The client is no longer asking a terminal program to print a result; it is speaking to a long-lived agent service. The protocol covers initialization, session creation or loading, prompts, streamed messages, reasoning chunks, tool updates, and permission requests. An editor can render those events in its own panels, and an SDK can decide how to display or store them. Grok Build also exposes extensions for filesystem work, Git, worktrees, search, terminals, and session management, but the important design point is that these extensions sit behind a named protocol boundary.
The shared subject is therefore not the screen. It is the agent runtime behind the screen, the command line, or the editor connection. The repository describes that runtime as a Rust application that understands a codebase, executes shell commands, edits files, searches the web, and manages long-running tasks. It also records a source revision because the public tree is synchronized from a larger monorepo. Those facts establish what the project is designed to do; they do not establish how fast it is, how widely it is adopted, or whether it is better than another coding agent.
This distinction gives the rest of the system a useful boundary. We can ask how a client request is represented, how a session keeps state, how the model chooses a tool, how a workspace turns that choice into an effect, and how the result returns to both the user and the next model turn. We do not need to begin with a catalogue of every slash command or crate. We need the path by which intention becomes action.
From model output to local agency
A language model can produce a proposed command or an edit, but a proposal is not yet a local side effect. Grok Build inserts several layers between the two. A client sends a request to an agent process. The agent routes it to a resident session. The session carries the conversation, tool context, permissions, model configuration, and workspace relationship. The model produces text and tool calls. A typed tool layer interprets those calls. Workspace operations connect them to the local filesystem, terminal, version-control state, and other resources. The system then emits structured updates and persists enough state for the next turn.
The session is the first major ownership boundary. In the shell implementation, an agent owns the client connection and routes commands to a session actor through a command channel. The session actor has its own chat history and tool context. It receives prompts, cancellation, shutdown requests, model changes, and background-task events; it also sends session notifications back through a gateway. This arrangement matters because the interface can change without moving conversation state into the interface itself. A TUI, a headless invocation, and an ACP client can attach to the same kind of stateful session boundary.
The turn is not a single blocking function either. A prompt may be admitted immediately or placed into a queue. Once a turn is running, model text can stream while tool calls are being prepared and executed. Tool updates have their own identity and status, so a client can distinguish an in-progress command from a completed result or a failed call. Cancellation can target the running session and, where appropriate, associated child work. At the end, the result is not only a sentence for the human: it is also material that the session can persist and expose as context for a later turn.
The typed tool layer is the second boundary. Grok Build's registry gives tools namespaces, identifiers, kinds, input schemas, configuration parameters, requirements, and output conversion. A terminal tool can require background-task and kill-task capabilities when background execution is enabled. A file-edit tool can require a read capability unless its configuration changes that relationship. This is more informative than a flat list of functions because the registry describes what a tool needs in order to be meaningful in a particular session.
ToolBridge sits between that registry and the session. It owns the finalized toolset, exposes model-facing definitions, holds shared resources, and dispatches calls. The session's local dispatch path routes a prepared call through WorkspaceOps::call_tool, rather than allowing each model-facing tool to reach into the host independently. That separation makes it possible to inject a filesystem, terminal backend, notification handle, session identity, or other resource, and it gives the workspace a place to apply its own rules about paths, toolsets, and turn boundaries.
The result is a control loop rather than a one-way pipeline. A model decision reaches a tool; the tool produces a structured result and often a notification; the session records or displays that result; the model sees the prompt-ready form on the next turn. If an exact file replacement fails because the text appears more than once, the tool can explain the ambiguity and ask for a more specific match. If a terminal command becomes a background task, the tool can return a task identifier and let later notifications report completion. Recovery information is part of the action's meaning.
The questions that make the system legible
The most useful way to read Grok Build is to follow ownership. The client owns the request and the presentation choice. The agent process owns the connection and routes requests. The session actor owns conversation and turn coordination. The model proposes reasoning and tool calls. The registry defines which typed operations are available. Workspace operations own the relationship to files, terminals, version control, and turn hooks. Policy and sandbox layers constrain what those operations may do. Persistence and event streams preserve enough evidence for a user, client, or later turn to understand what happened.
This map also explains why a feature list is a weak mental model. “It can edit files” hides several separate questions: Which edit tool was exposed? What filesystem did it receive? Was the target inside the intended workspace? Did the edit match one location or many? Was a file-written event emitted? Did a permission rule ask or deny? Can the user see the diff? What gets persisted if the process stops immediately afterward? The visible capability is the end of a chain of decisions.
The same reasoning applies to commands. “It can run a shell” does not mean that every model-generated string is treated as equally safe or equally durable. The terminal tool has foreground and background modes, output limits, timeouts, task identities, and notifications. Later chapters will examine the permission evaluator and the OS-level sandbox separately, because a permission decision answers whether a requested operation should run while a sandbox limits what the process can reach even after approval. Combining those layers is different from replacing one with the other.
The model also has to be extended across time. A session may be resumed, compacted, forked, rewound, or supplied with project rules and optional memory. A background child may finish after the parent has moved on. A monitor may emit an event while no model turn is active. These are not exotic additions to a chat window; they are state-management problems. The product's usefulness depends on whether ownership and evidence remain clear as the number of live states grows.
That gives readers a practical test for every later mechanism in this series. When Grok Build appears to do something impressive, ask what crosses the boundary, who owns the state, what event proves the transition, and what happens when the transition fails. When it appears to be safe, ask whether the claim comes from a tool contract, a permission policy, a hook, a workspace check, or kernel enforcement. When it appears to remember, ask whether the information is authoritative current state, a replayable event, a derived cache, or optional stored context.
The central conclusion is modest but powerful: Grok Build is best understood as a system for turning model output into bounded, observable local agency. Its interfaces determine how a person or program engages with that agency, but the deeper design lives in the session, tool, workspace, control, and persistence boundaries underneath. The next step is to examine the resident session itself and trace one request through a coordinated, cancellable, observable turn.