Grok Build

Host entry

A terminal command owns the process, current working directory, stdin/stdout, shell environment, and project file discovery.

Host owns

The CLI host owns agent loop timing, approval prompts, tool execution, session files, and how hook or MCP subprocesses are launched.

Connector role

agent-connector can only write the host's documented CLI config, prompt, memory, hook, MCP, or package files and point them at the home binary. Current wired connector surfaces: MCP server, Hooks, Commands, Skills, Subagents, Memory.

Implementation consequence

A CLI surface is byte-addressable and smoke-testable from a temporary HOME, but terminal UI behavior still belongs to the host process. Visible host-native gaps for this surface: Statusline handler.

Source pass

Current source review findings are kept as the first architecture section so readers can separate external evidence from the generated local coverage model.

• Grok Build is xAI's official agent (Apache-2.0, binary artifact xai-grok-pager, installed as `grok`), distinct from the community superagent-ai/grok-cli behind the grok-cli adapter id.
• Both products default to ~/.grok but never share a file: Grok Build keys on config.toml, Grok CLI on user-settings.json, so each adapter claims the directory only when the sibling's marker is absent.
• Hooks fire PascalCase events that map 1:1 to twelve canonical agent-connector events; StopFailure, StopCancelled, and PermissionDenied ride the nativeHooks escape hatch, and PermissionRequest stays unset because PermissionDenied is a post-decision observation.

Runtime boundary

The adapter target is the Grok Build CLI process. The host owns the model loop, permission system, folder trust, and the TUI; agent-connector writes only the files the user guide documents under $GROK_HOME and <project>/.grok.

• Project-scope config.toml contributes exactly [mcp_servers], [plugins], [permission], and [mcp] max_output_bytes; every other table is read from the user file only.
• Project hooks require folder trust; user hooks are always trusted.
• This is not the community Grok CLI: same default directory, different vendor, product, and config file.

MCP registration

MCP servers live in TOML under [mcp_servers.<name>] with stdio keys (command, args, env, enabled, startup_timeout_sec, tool_timeout_sec) or remote keys (url, headers). TOML has no interpolation, so environment references resolve to literals at install time.

• User scope: $GROK_HOME/config.toml. Project scope: <project>/.grok/config.toml.
• Detection keys on config.toml so the shared ~/.grok directory is never misreported as a Grok CLI install.

Hook bridge

Hooks are JSON files in $GROK_HOME/hooks/*.json or <project>/.grok/hooks/*.json using the Claude-compatible { hooks: { <Event>: [ { matcher, hooks: [ { type: "command", command, timeout } ] } ] } } shape. agent-connector writes its own file instead of merging into the user's config.toml [[hooks.<Event>]] block.

• Twelve PascalCase events map 1:1 to canonical names, from SessionStart to PostCompact.
• StopFailure, StopCancelled, and PermissionDenied have no canonical analog and ride the nativeHooks escape hatch.
• PermissionRequest stays unset: PermissionDenied fires after the denial and is documented as non-blocking.

Content surfaces

Commands are flat markdown files whose filename stem is the slash-command name, skills are <name>/SKILL.md with Anthropic-format frontmatter, and subagents are agents/<name>.md with name, description, tools, and model frontmatter.

• Memory is AGENTS.md loaded from the repo root down to the cwd, deeper files winning; user scope adds $GROK_HOME/rules/*.md.
• Commands are prompt templates with no shell-exec affordance, so the actions surface is a host N/A rather than an adapter gap.

Marketplace and host-only affordances

Grok Build has a native [ui.status_line] type="command" surface that receives JSON on stdin. The host supports it, the adapter does not write it yet, so it is the one genuine coverage gap on this row.

• A [plugins] table exists in project config, but no marketplace driver is wired for it.
• Official xAI ownership is the affordance to highlight against the community Grok CLI row.

Host-specific shape

Grok Build is xAI's official Rust CLI agent: MCP in $GROK_HOME/config.toml, Claude-compatible hook JSON under .grok/hooks, commands, skills, agents, and AGENTS.md memory are wired; its native [ui.status_line] command is an adapter gap.

• Form factor: CLI.
• Native surfaces: MCP server, Hooks, Commands, Skills, Subagents, Memory, Statusline handler.
• Wired surfaces: MCP server, Hooks, Commands, Skills, Subagents, Memory.
• Visible gaps: Statusline handler.

Hooks

Hooks enter through a host-launched command that exchanges event JSON over stdio.

MCP

The adapter writes this host's native MCP registration dialect, including its root key, scope, transport fields, and environment syntax.

Memory

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace and affordances

Current install is a direct native-file write path; any package artifact is manual unless a driver is added.

• Runtime handlers: none.
• User-visible affordances: Users see managed commands + skills + subagents + memory surfaces after install; runtime-only surfaces stay behind the host boundary..