feat(integrations): add Grok Build CLI harness

.github/workflows/ci.yml

@@ -289,6 +289,7 @@ jobs:
             packages/integrations/deepagents-sdk/dist/**
             packages/integrations/fx-sdk/dist/**
             packages/integrations/cursor-sdk/dist/**
+            packages/integrations/grok-build-sdk/dist/**
             packages/evals/dist/**
           retention-days: 1
 

packages/docs/docs.json

@@ -70,6 +70,7 @@
                   "v4/integrations/cli-agents/overview",
                   "v4/integrations/cli-agents/claude-code",
                   "v4/integrations/cli-agents/codex",
+                  "v4/integrations/cli-agents/grok-build",
                   "v4/integrations/cli-agents/cursor",
                   "v4/integrations/cli-agents/fx",
                   "v4/integrations/cli-agents/pi"

packages/docs/v4/integrations/cli-agents/grok-build.mdx

@@ -0,0 +1,117 @@
+---
+title: "Grok Build"
+description: "Give Grok Build persistent Stagehand browser tools over MCP/stdio."
+---
+
+The Grok Build integration connects the Grok CLI to the Stagehand facade MCP server over MCP/stdio. One server process owns the browser, so page state survives across `run`, `snapshot`, and `screenshot` calls.
+
+<Note>
+Stagehand ships this experimental integration from the repository rather than publishing it as a standalone adapter.
+</Note>
+
+## Prerequisites
+
+- Node.js 24 or newer
+- pnpm 11.10.0
+- The Grok Build CLI and either `XAI_API_KEY` or an existing `grok login`
+- A current Google Chrome installation for local browser mode
+
+## Quickstart
+
+<Steps>
+  <Step title="Clone and build Stagehand">
+```bash
+git clone https://github.com/browserbase/stagehand.git
+cd stagehand
+pnpm install --frozen-lockfile
+pnpm exec turbo run build \
+  --filter @browserbasehq/stagehand-integrations
+```
+  </Step>
+  <Step title="Install and authenticate Grok Build">
+```bash
+npm install --global @xai-official/grok
+grok login
+# or: export XAI_API_KEY="your-xai-api-key"
+```
+  </Step>
+  <Step title="Configure the Stagehand MCP server">
+Copy `packages/integrations/grok-build/.grok/config.toml` into the project where Grok will run, then replace the facade path and browser credentials. Grok merges project MCP configuration over its user settings:
+
+```toml
+[mcp_servers.stagehand]
+command = "node"
+args = [
+  "/absolute/path/to/stagehand/packages/integrations/core/dist/facade/stdio-server.mjs",
+  "--max-screenshot-base64-bytes=60000",
+]
+startup_timeout_sec = 60
+tool_timeout_sec = 300
+
+[mcp_servers.stagehand.env]
+STAGEHAND_BROWSER = "browserbase"
+BROWSERBASE_API_KEY = "bb_live_..."
+```
+
+Start Grok from that project so it loads `.grok/config.toml` and the included `AGENTS.md`.
+  </Step>
+  <Step title="Choose the browser">
+The example defaults to Browserbase when `BROWSERBASE_API_KEY` is set in the MCP server env. For local Chrome:
+
+```toml
+[mcp_servers.stagehand.env]
+STAGEHAND_BROWSER = "local"
+```
+  </Step>
+  <Step title="Run a browser task">
+```bash
+cd packages/integrations/grok-build
+grok
+```
+
+At the prompt, enter:
+
+```text
+Use the Stagehand browser tools to open https://example.com, take a snapshot,
+and report the heading with its snapshot ID.
+```
+  </Step>
+</Steps>
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `XAI_API_KEY` | Credential for the Grok CLI. Grok does not need to forward it to the MCP child. |
+| `STAGEHAND_BROWSER` | Select `local` or `browserbase`. |
+| `BROWSERBASE_API_KEY` | Required for Browserbase. |
+| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. |
+| `STAGEHAND_MODEL_NAME` | Optional model for Stagehand AI methods called inside `run`. |
+| `STAGEHAND_MODEL_API_KEY` | Required with `STAGEHAND_MODEL_NAME`; the MCP child does not receive Grok credentials. |
+
+Put Stagehand and Browserbase values in `[mcp_servers.stagehand.env]`. Grok does not expand shell variables in config values; paste the real keys or generate this file from your environment.
+
+## Keep the browser session alive
+
+The package mounts one facade MCP server for the Grok session and raises MCP startup and tool timeouts because browser launches exceed the defaults. Preserve that lifetime if you adapt the integration; a new process per tool call starts a new browser.
+
+The MCP child receives only Stagehand and Browserbase configuration plus the process values required to launch Node. The host's model credential remains in the Grok process.
+
+## Headless one-shot runs
+
+Interactive sessions can approve tool calls when prompted. A `-p` run cannot accept approval responses, so tasks that require approval may fail. Pass `--always-approve` only when you want Grok to run tools without asking:
+
+```bash
+cd packages/integrations/grok-build
+grok \
+  --always-approve \
+  -p "Open https://example.com, snapshot it, and report the heading."
+```
+
+<Warning>
+`run` executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the [integration security boundary](/v4/integrations/cli-agents/overview#security-boundary).
+</Warning>
+
+<Card title="Grok Build integration source" icon="github" href="https://github.com/browserbase/stagehand/tree/main/packages/integrations/grok-build">
+  Read the CLI configuration, MCP mount, and Stagehand tool guidance.
+</Card>

packages/docs/v4/integrations/cli-agents/overview.mdx

@@ -14,6 +14,8 @@ CLI agents that support stdio MCP can connect to the Stagehand MCP adapter. One
 | --- | --- | --- |
 | Claude Code | MCP server configured in a project `.mcp.json`. | [Claude Code](/v4/integrations/cli-agents/claude-code#connect-a-running-claude-code-cli) |
 | Codex | MCP server configured in `~/.codex/config.toml`. | [Codex](/v4/integrations/cli-agents/codex#connect-a-running-codex-cli) |
+| Grok Build | MCP server configured in a project `.grok/config.toml`. | [Grok Build](/v4/integrations/cli-agents/grok-build#quickstart) |
+| Cursor | Local Cursor SDK session with a project MCP server. | [Cursor](/v4/integrations/cli-agents/cursor) |
 | fx | MCP server configured in `~/.fx/mcp.json`. | [fx](/v4/integrations/cli-agents/fx) |
 | Pi | Native extension that registers Stagehand tools directly. | [Pi](/v4/integrations/cli-agents/pi) |
 

packages/docs/v4/integrations/overview.mdx

@@ -41,6 +41,9 @@ Give a coding agent browser tools for tasks such as checking a running applicati
   <Card title="Codex" icon="/images/integrations/codex.svg" href="/v4/integrations/cli-agents/codex">
     Give a Codex agent persistent Stagehand browser tools over MCP/stdio.
   </Card>
+  <Card title="Grok Build" icon="/images/integrations/grok-build.svg" href="/v4/integrations/cli-agents/grok-build">
+    Give a Grok Build agent persistent Stagehand browser tools.
+  </Card>
   <Card title="Cursor" icon="/images/integrations/cursor.svg" href="/v4/integrations/cli-agents/cursor">
     Give a local Cursor SDK agent persistent Stagehand browser tools over MCP/stdio.
   </Card>

packages/evals/docs/harness-contract.md

@@ -20,13 +20,13 @@ historical harness default. Only positive safe integers are accepted.
 and requested reasoning settings where supported. Equal budget numbers do not
 mean equal work:
 
-| Harness                                 | Counted unit          |
-| --------------------------------------- | --------------------- |
-| Codex, Cursor, DeepAgents               | Tool calls            |
-| Eve                                     | Successful tool calls |
-| Mastra                                  | Model steps           |
-| fx                                      | Agent steps           |
-| Claude Code, Pi, Claude CUA, Gemini CUA | Turns                 |
+| Harness                                             | Counted unit          |
+| --------------------------------------------------- | --------------------- |
+| Codex, Cursor, DeepAgents                           | Tool calls            |
+| Eve                                                 | Successful tool calls |
+| Mastra                                              | Model steps           |
+| fx                                                  | Agent steps           |
+| Claude Code, Pi, Claude CUA, Gemini CUA, Grok Build | Turns                 |
 
 These are execution limits, not comparable measures of model efficiency.
 

packages/evals/framework/benchHarness.ts

@@ -27,6 +27,8 @@ import { runFxAgent } from "./fxRunner.js";
 import { FX_TOOL_SURFACES, prepareFxToolAdapter } from "./fxToolAdapter.js";
 import { runCursorAgent } from "./cursorRunner.js";
 import { CURSOR_TOOL_SURFACES, prepareCursorToolAdapter } from "./cursorToolAdapter.js";
+import { runGrokBuildAgent } from "./grokBuildRunner.js";
+import { GROK_BUILD_TOOL_SURFACES, prepareGrokBuildToolAdapter } from "./grokBuildToolAdapter.js";
 import {
   buildExternalHarnessTaskPlan,
   type ExternalHarnessTaskPlan,
@@ -383,6 +385,14 @@ export const cursorHarness = defineExternalHarness({
   runAgent: runCursorAgent,
 });
 
+export const grokBuildHarness = defineExternalHarness({
+  harness: "grok_build",
+  supportedToolSurfaces: GROK_BUILD_TOOL_SURFACES,
+  defaultModels: ["grok-build/auto" as AvailableModel],
+  prepareToolAdapter: prepareGrokBuildToolAdapter,
+  runAgent: runGrokBuildAgent,
+});
+
 export const claudeCuaHarness = defineExternalHarness({
   harness: "claude_cua",
   supportedToolSurfaces: CLAUDE_CUA_TOOL_SURFACES,
@@ -409,6 +419,7 @@ const harnessRegistry = new Map<Harness, BenchHarness>([
   ["deepagents", deepagentsHarness],
   ["fx", fxHarness],
   ["cursor", cursorHarness],
+  ["grok_build", grokBuildHarness],
   ["claude_cua", claudeCuaHarness],
   ["gemini_cua", geminiCuaHarness],
 ]);

packages/evals/framework/costEstimate.ts

@@ -52,6 +52,7 @@ export interface BilledCost {
  * | mastra      | never (AI SDK usage has no dollars)     | —                     | provider SDK with our key → computed <provider>_api   |
  * | deepagents  | never (LangChain usage_metadata)        | —                     | provider SDK with our key → computed <provider>_api   |
  * | cursor      | never                                   | —                     | subscription → unavailable                            |
+ * | grok_build  | end event `total_cost_usd`             | xai                   | unreported → unavailable                              |
  */
 const REPORTED_CHANNEL: Readonly<Record<string, string>> = {
   claude_code: "anthropic_api",
@@ -60,6 +61,7 @@ const REPORTED_CHANNEL: Readonly<Record<string, string>> = {
   eve: "ai_gateway",
   pi: "pi_catalog",
   fx: "fx_gateway",
+  grok_build: "xai",
 };
 
 /** Harnesses whose unreported bill is our own provider-API spend, priceable at list. */