# ADR 004: Grok Build

- HTML version: https://robbiepalmer.me/projects/homelab/adrs/004-grok-build
- Project: Home Lab (https://robbiepalmer.me/projects/homelab.md)
- Status: Accepted
- Date: 2026-08-02

# Context

The hub hosts multiple coding agents so I have independent usage allowances
and model diversity ([Claude Code](/projects/homelab/adrs/002-claude-code)
and [Codex](/projects/homelab/adrs/003-codex) are already accepted). Grok's
models are a meaningful third model family, and Grok Build is xAI's terminal
coding agent: a full-screen TUI with a plan mode, parallel subagents, skills,
plugins, hooks, MCP servers, and a headless `-p` mode for scripts.

For the hub, what matters is:

* **A different model family with its own subscription.** Using Claude,
  OpenAI, *and* Grok spreads the availability and pricing risk across three
  providers rather than two.
* **Extensibility.** AGENTS.md, plugins, hooks, and MCP servers work out of
  the box, so it slots into the same agent conventions as the rest of the
  stack.
* **Fits the orchestration layer.** Like the other agents, it should be
  runnable from the single orchestration surface rather than only as a
  standalone TUI.

# Decision

Install **Grok Build** on the Mac mini alongside Claude Code and Codex.

Grok Build runs as the `grok` CLI, installed per
[xAI's official instructions](https://x.ai/cli), authenticates with an
xAI/SuperGrok account, and is available both as
an interactive agent and headless (`grok -p`) for scripted jobs. Managed from
the same orchestration surface as the other agents, its sessions, diffs, and
PR workflow live in the same mobile-friendly place, and its allowance stays
independent of Claude and OpenAI.

# Alternatives

## Skip Grok; stay on two providers

* **Pros**: Two agents already give redundancy; less to install and maintain.
* **Cons**: Leaves the third major model family unused. If both Claude and
  OpenAI are constrained at once, there's no third fallback.
* **Decision**: Rejected. Provider diversity is the stated resilience
  strategy; Grok Build adds it cheaply since the hub already exists.

## Use Grok only via the API from another tool

* **Pros**: No separate agent to manage.
* **Cons**: Loses Grok Build's agent harness (skills, plugins, subagents,
  worktrees) and adds per-token cost instead of using a subscription.
* **Decision**: Rejected. The standalone agent is free to run against my
  existing subscription.

## Grok Build as the primary agent

* **Pros**: One agent to learn deeply.
* **Cons**: Concentrates workflow on a beta product and one provider;
  contradicts the multi-agent resilience goal.
* **Decision**: Rejected. Grok Build is a complement, not a replacement.

# Consequences

### Pros

* **Third independent provider** for agent work, with its own allowance and
  reset cadence.
* **Different reasoning model** — route work to whichever agent handles it
  best.
* **Fits the existing conventions** (AGENTS.md, MCP, plugins) and is driven
  from the same surface as the rest.
* **Open source** since July 2026, with the freedom to point it at any
  model provider rather than being locked to xAI's.

### Cons

* **Another agent to authenticate and update.**
* **Early-beta risk**: Grok Build's harness is younger than Claude Code's.
* **xAI dependency**: availability and pricing of Grok models are outside my
  control.

---

Markdown index of this site: https://robbiepalmer.me/llms.txt