Integration: Grok Build CLI (xAI)

Status: Researched, not yet built. Package will be @agenticmail/grok-build. ~80% architectural overlap with @agenticmail/claudecode.

Reality check

Grok Build CLI shipped on 2026-05-14 as an early beta from xAI, announced at x.ai/news/grok-build-cli. Access is gated to SuperGrok Heavy subscribers ($300/mo, with a $99/mo intro offer on a "SuperHeavy" tier). It is not open-source — there is no xai-org/grok-build repo on GitHub. xAI's only public repos are xai-sdk-python and xai-cookbook. No @xai-org npm SDK exists.

Install: curl -fsSL https://x.ai/cli/install.sh | bash — single-line shell installer, not npm-published.

Distinct from Grok Build: a popular community CLI at github.com/superagent-ai/grok-cli (npm: grok-dev, ~2.4k stars). xAI's announcement says Grok Build supports "AGENTS.md, plugins, hooks, skills, and MCP servers… out of the box" — wording strongly suggesting xAI cloned the established Claude-Code-style surface area (which the community superagent-ai/grok-cli also implements). Because the official CLI is closed-beta and behind a paywall, we cannot verify its exact config-file paths and JSON shapes from public sources. The schemas below are confirmed for superagent-ai/grok-cli; xAI's Grok Build is announced to support the same primitives but the precise file layout may differ. Treat the community CLI schema as a high-confidence proxy until we obtain a SuperGrok Heavy subscription.

1. MCP server registration — supported

Grok Build's announcement explicitly lists MCP. In superagent-ai/grok-cli the config lives at .grok/settings.json (project) and ~/.grok/user-settings.json (user). The block is an array, not an object map like Claude's:

{
  "mcpServers": [
    { "name": "agenticmail", "command": "node", "args": ["/path/to/server.js"] }
  ]
}

Auto-writing our entry on install is a one-line file-merge — same pattern as our ~/.claude.json patcher, just a different path and array-vs-object shape. Also exposed via grok mcp add <name> --transport ... subcommand for scripted install.

2. Sub-agents as native callable agents — first-class

Grok Build markets parallel subagents ("up to 8 concurrent", "16-agent Heavy architecture") and "delegates work to specialized subagents that run in parallel… launch subagents in their own worktrees." The community CLI defines them in ~/.grok/user-settings.json:

{
  "subAgents": [
    { "name": "ope-inbox", "model": "grok-4.3", "instruction": "..." }
  ]
}

Reserved names: general, explore, vision, verify, computer. Built-in delegation tools include task (foreground) and delegate (background). This is a closer match to Claude Code's Agent/subagent_type than expected — every AgenticMail account maps cleanly to one subAgents[] entry plus a corresponding MCP-exposed toolset.

3. Lifecycle hooks — richer than Claude Code

Confirmed events in ~/.grok/user-settings.json:

• PreToolUse, PostToolUse, PostToolUseFailure
• UserPromptSubmit
• SessionStart, SessionEnd
• Stop, StopFailure
• SubagentStart, SubagentStop
• TaskCreated, TaskCompleted
• PreCompact, PostCompact
• Notification, InstructionsLoaded, CwdChanged

Schema:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "./mail-hook.sh", "timeout": 10 }]
      }
    ]
  }
}

I/O contract identical to Claude Code: JSON on stdin, JSON on stdout, exit 0 = ok, exit 2 = block, other = non-blocking error. Our existing mail-hook ports over with only path changes. Bonus: SubagentStart/SubagentStop/TaskCreated/TaskCompleted give us finer-grained observability than Claude Code offers.

4. Headless / programmatic mode — supported, with caveats

-p / --prompt flag exits after one response. xAI's announcement: "Headless mode (-p) allows easily running agents inside scripts and automations. The CLI also provides full ACP support to build your own bots and agent orchestration apps." ACP = Agent Client Protocol (the Zed-originated standard) — meaning a stream-based protocol over stdio, not just one-shot CLI invocation. This is strictly better than Claude Code's headless mode for daemon use.

Gap vs. Claude: there is no official Node.js SDK equivalent to @anthropic-ai/claude-agent-sdk's query(). xAI publishes only xai-sdk-python (gRPC, Apache-2.0), which talks to the model API directly — not to the CLI agent loop. Our dispatcher daemon options:

• (a) Spawn grok -p "<prompt>" as a subprocess (same shape as our current Claude shell-out fallback), or
• (b) Open an ACP session over stdio and stream turns — more work, but gives us a long-lived agent with persistent state instead of fresh boots per turn.

(b) is the right long-term answer; (a) ships in a day.

5. Installation pattern

• Install: curl -fsSL https://x.ai/cli/install.sh | bash (binary installer, not npm).
• Config: ~/.grok/user-settings.json + per-project .grok/settings.json.
• Auth: SuperGrok Heavy sign-in, not API-key by default (though GROK_API_KEY env var works in the community CLI).
• Sessions: persistent, --session latest resumes.

We can't bundle Grok Build as a peer-dep the way we do with @anthropic-ai/claude-agent-sdk. Our installer becomes a config-patcher only: detect ~/.grok/, merge our mcpServers[], subAgents[], and hooks entries, done.

Verdict — feasible. ~80% architectural overlap with the Claude integration.

The shape of @agenticmail/grok-build:

1. Postinstall script detects ~/.grok/, deep-merges into user-settings.json: our MCP server entry (array push), one subAgents[] entry per AgenticMail account, and UserPromptSubmit / SessionStart / Stop hooks pointing at our existing hook binaries (path-rewritten).
2. MCP server is the same Node binary we ship for Claude — protocol is identical, no rework.
3. Hook scripts port 1:1 from claudecode/src/mail-hook.ts; only the harness path differs. The same defensive clean-exit pattern (process.exit(0) everywhere) applies to avoid freezing the Grok harness.
4. Dispatcher daemon ships with a --harness=grok mode that shells out to grok -p initially (parity with current behavior), then upgrades to an ACP-over-stdio client once we have a paid subscription to validate the protocol stream.
5. No SDK dependency — Grok Build is a closed binary distributed via shell installer; we never require() it.

Blockers / unknowns to resolve before coding

• Grok Build's exact config paths are inferred from the community CLI, not verified against the closed beta. Risk: xAI may have moved files to ~/.config/grok-build/ or similar. Action item: budget $99 for a one-month SuperGrok Heavy seat to confirm paths, hook stdin/stdout shape, and ACP wire format before committing engineering time.
• No official JS SDK means we cannot replicate the in-process query() ergonomics. ACP-over-stdio is the workaround, not a blocker.
• "Skills" support is mentioned by xAI but the on-disk format is unconfirmed for Grok Build (community CLI uses .agents/skills/<name>/SKILL.md). Low-priority for AgenticMail integration anyway.

Sources

• x.ai/news/grok-build-cli — official announcement
• github.com/superagent-ai/grok-cli — community CLI, proxy for schema
• grokipedia.com/page/Grok_CLI — config reference
• github.com/xai-org/xai-sdk-python — only official SDK (Python, model-level not agent-level)