Grok Build (experimental)

Happier can run Grok Build through the local grok CLI using the Agent Client Protocol (ACP).

Install Grok Build

In Happier, open Settings → AI & Agents → AI backends → Grok to check whether the CLI is available on the selected machine and run its vendor installer.

For a manual installation, use xAI's current Grok Build CLI instructions, then verify:

grok --version

Happier checks PATH and common installation locations, including ~/.grok/bin. If needed, set HAPPIER_GROK_PATH to the absolute path of the grok executable.

Happier launches the provider in update-safe ACP mode, equivalent to:

grok --no-auto-update agent stdio

Authenticate

Grok Build supports either an xAI API key or its native cached login.

API key

Set XAI_API_KEY in the environment used by the Happier CLI or daemon. Happier detects that variable without copying its value into session metadata or logs.

Native login

From Settings → AI & Agents → AI backends → Grok, start the normal login flow or the device-code flow for a headless or remote machine. The equivalent terminal commands are:

grok login
grok login --device-auth

Grok Build does not currently provide Happier with a reliable non-interactive cached-login status check. The settings page therefore continues to show Unknown for cached login, while ACP startup independently validates that account for each session; Unknown does not by itself mean that you are logged out.

Sessions and questions

• Happier stores the Grok session identity and can request an experimental resume after the provider process restarts.
• While a Grok turn is active, an ordinary follow-up can steer it through Grok's x.ai/interject ACP extension. Send now remains a separate cancel-and-successor action, so it does not depend on steering support.
• Grok's structured questions use Happier's native structured-question UI. Zero-option questions accept freeform text, and questions with advertised choices can accept an additional freeform answer; Happier preserves commas and newlines and maps freeform text to Grok's Other answer with its notes annotation.
• Cancellation uses the shared ACP lifecycle, so a cancelled prompt should not prevent a later prompt in the same Happier session.
• Grok workflow, goal, and subagent notifications appear through Happier's existing workflow activity, work-state, and subagent surfaces. Live and replay notification names are accepted, including the nested form used when a session resumes.

Resume and structured-question behavior depend on the installed Grok Build version. Use a current CLI release: Happier requires an authentication method advertised by Grok and separately validates every structured-question payload at the provider boundary.

Current capability limits

• Models: Happier renders only the models advertised by the active Grok ACP session and applies a selected model through the standard live model-switch request. Each model shows a reasoning-effort control only when that model advertises supported effort values. When Grok does not advertise a selectable model inventory, Happier leaves model choice to the CLI instead of inventing a fallback model ID.
• Model switch failures: Grok switch errors are surfaced to the session instead of being treated as success, and the last provider-confirmed model remains authoritative.
• Usage: Happier reads Grok's ACP usage metadata, including cached and reasoning detail, without double-counting token classes that Grok already includes in input or output. Provider-reported cost is shown only when Grok marks it complete.
• Tool progress: rapid in-progress updates are coalesced and cumulative text is bounded, while final completed, failed, or cancelled updates are always retained.
• MCP tools: native MCP delivery is experimental.
• Images and session media: trusted prompt images are projected through Happier's shared ACP media path. Output media and general session-media extraction remain unsupported unless the provider advertises and the shared runtime proves those separate contracts.
• Prompt completion compatibility: standard ACP completion remains primary. Happier also accepts correlated x.ai/session/prompt_complete and observed _x.ai/session/prompt_complete terminal evidence only for the current open, non-cancelled session turn; missing or stale extension notifications never delay or settle another turn.
• Session listing, forking, rollback, and vendor-state handoff: not currently supported.
• Platforms: the integration includes macOS, Linux, and Windows install/detection paths, but platform behavior still depends on the installed xAI CLI release.

These limits are intentional capability declarations. Happier does not emulate unadvertised provider behavior or use private completion methods as a fallback.

Troubleshooting

“Grok Build not found”

1. Verify grok --version works on the selected machine.
2. Restart Happier after installing the CLI.
3. If the binary is outside the usual locations, set HAPPIER_GROK_PATH to its absolute path.

Authentication is unavailable

1. Confirm XAI_API_KEY is present in the Happier CLI or daemon environment, or run one of the native login commands above.
2. Retry the session so Happier can re-run ACP initialization and select one of the authentication methods advertised by the CLI.
3. If an older CLI silently drops ACP requests, update Grok Build and retry.

For the shared authentication flow, see Provider authentication.

Related

• Agent capabilities — what this agent supports, generated from the manifest.
• Choosing an agent
• Model and engine selection
• Agent authentication