Grok Provider

What it is

Omniscio can spawn Claude-Code-style sessions backed by Grok Build (grok, xAI's agentic coding CLI) as an alternative provider, alongside claude (the default), codex, gemini, antigravity, the Anthropic-compatible deepseek / kimi / glm / minimax / meta, cursor, hermes, pi, opencode, and openclaw. Grok Build is a local CLI coding agent with its own models (grok-build-0.1, the grok-4.x family) and its own auth — so a Grok session is "a different agent and a different model," not Claude in a different harness. It deliberately mirrors Claude Code's CLI, so it slots into Omniscio's one-shot-cli engine family cleanly.

v1.x parity (2026-08, corrected 2026-09). The original integration targeted grok 0.2.x. Live measurement on grok 0.2.93 shows ACP image blocks and grok mcp already work — capabilities.images and capabilities.mcp stay statically true and are not gated on a CLI 1.0.0 floor (wiring that floor would dark working features). Grok 1.x additionally stamps token usage + cost on the end frame. A 0.2.x end with no usage degrades on wire shape (usage: undefined → "cost not reported"), not on a version probe. CONFIRMED (parent session 110e02d0, grok 0.2.93 capture): {"type":"end","stopReason":"EndTurn",…} — no usage block, no cost ticks.

What the user sees

A Grok session looks almost identical in the sidebar and main pane to a Claude session — same status dots, same streaming bubbles, same Ctrl+Enter to send. The differences:

• Grok icon (a monochrome spark) in the session header — like every non-default provider.
• Token-by-token streaming. --output-format streaming-json emits per-token text deltas. Grok also streams its reasoning as thought frames; Omniscio consumes those as liveness (feeding the no-first-output watchdog during a silent reasoning phase) and never renders them as the answer.
• No tool markers. Grok's headless stream emits no structured tool-call frames (a file write still happens — Grok narrates it in reasoning), so a turn shows the answer text but no ▸ Edit chips.
• Real cost. A v1.x turn reports token usage and a dollar cost (exact when xAI stamps it, else token-priced) — the per-session spend line shows a real figure, not "cost not reported" (registry costReporting: 'estimated'). A 0.2.x CLI still reads "cost not reported."
• Images. Attach an image to a Grok session and the model actually sees it (Grok is the first one-shot-cli provider with real vision).

Where to find it

How to enable

Three gates, all off by default (opt-in, like every alternative provider):

1. Master toggle — Settings → Accounts → "Show alternative AI providers".
2. Install the CLI — curl -fsSL https://x.ai/cli/install.sh | bash (installs to ~/.grok/bin). Omniscio finds it there automatically even when it is not on the GUI's PATH (the resolver probes ~/.grok/bin/grok[.exe] and resolves by existence).
3. Settings → Accounts → Grok: flip Allow Grok sessions in any project, then authenticate one of two ways (below).

Authentication — sign in OR a key

Grok authenticates a headless turn with either:

• A signed-in Grok account (preferred). Click Sign in with Grok on the card — Omniscio launches grok login in a visible terminal; finish in the browser and the session token lands in <GROK_HOME>/auth.json, which v1.x uses and prefers. This uses your SuperGrok / X Premium+ subscription — no per-token API key needed. (Desktop-only; on Linux run grok login in a terminal yourself.)
• An xAI API key (fallback). Paste an xAI API key (XAI_API_KEY, from console.x.ai — xAI's own key, NOT an Anthropic key). It is injected as an env var, never argv, and is the same key Grok voice/TTS uses (xaiApiKey) — if you already set that up for voice, the field can stay blank. A dedicated grokApiKey overrides it when set.

Readiness gaps (surfaced with a one-click Settings deep-link): toggle-off, binary-missing, and auth-missing (neither signed in nor a key). The binary-status card (GROK_GET_STATUS) shows Installed (version …) / Checking… / an install hint + Recheck; negatives are never cached, so Recheck picks up a just-installed binary without a restart.

Multiple accounts

Omniscio can manage several Grok/SuperGrok accounts, each in its own isolated GROK_HOME (so several can be signed in at once). Add, switch the active one, or remove an account from Settings → Accounts → Grok — or from the condensed Grok tab in the lower-left account popover (the same grokAccounts slice + IPC; see account-indicator.md). The active account is the default for new Grok sessions, and each session runs under its bound account's auth.json. Mirrors Codex's multi-account subsystem — including how the account's folder is resolved and how it reaches grok login: the home is derived from the account id on every read rather than trusted from the stored column, and on macOS it rides inside the command text via /usr/bin/env because Terminal.app never inherits the spawning process's environment. Both mechanisms are shared code and are explained once in codex-provider.md.

How it behaves

Choosing the model

grok -m <id> per session. The picker lists grok-build-0.1 (xAI's purpose-built coding model — the seeded default), grok-4.7 (newest flagship, vision-capable), grok-4.6, grok-4.5, grok-4.3, and the grok-4.20-0309-reasoning / -non-reasoning general models. "Use default" omits the flag. For image input, pick a grok-4.x model. Reasoning effort is a separate --reasoning-effort axis Omniscio does not expose in v1.

No virtual project

Grok has no dedicated virtual project (unlike Codex's __codex__) — enable it and pick it per-session or per-project, like Cursor and Hermes.

Error states and fixes

• Grok card shows the install hint — the binary isn't detected. Install from x.ai/cli (lands in ~/.grok/bin), then click Recheck; if still missing right after a fresh install, restart Omniscio.
• "Grok needs you to sign in… or add an xAI API key" — neither auth path is set. Click Sign in with Grok, or add a key, in Settings → Accounts → Grok.
• "Grok's xAI account is out of API credits…" — a hard billing refusal (403). Retrying won't help and the key is fine — add credits / raise the spending limit at console.x.ai.
• "Grok's CLI reported an error… / returned no response" — usually a transient auth/quota/network blip; try again. Raw error text is logged but never shown raw (humanized, per CLAUDE.md "humanize, log the raw").

For agents

How it works under the hood

• Runtime kind one-shot-cli — one grok subprocess per turn (GrokSessionManager extending OneShotExternalSessionManager), streamed and resumed via a session id Omniscio controls.
• Invocation — grok --prompt-file <tmp> --output-format streaming-json --always-approve --cwd <workDir> [-m <model>] [--session-id <uuid> | --resume <id>]. The prompt rides a temp FILE (--prompt-file) to sidestep Windows' ~32 KB argv ceiling and stay newline-safe. A native .exe, so it spawns directly through spawnCliChild — no cmd.exe wrap.
• Auth — a signed-in account's auth.json (via a session-scoped GROK_HOME, preferred) OR XAI_API_KEY env (fallback, never argv). See "Authentication" above.
• Cost — the v1.x end frame stamps token usage always, plus an exact total_cost_usd_ticks for API-key traffic. grok-cost.ts uses the exact ticks when present, else prices the reported tokens from MODEL_PRICING (never fabricates a $), filed under the per-session model. A 0.2.x turn reports none → tokens/cost 0, "cost not reported".
• MCP — the session's MCP servers are written to grok's NATIVE [mcp_servers.*] TOML in <workDir>/.grok/config.toml (marker-delimited, git-excluded, scrubbed post-turn) + GROK_FOLDER_TRUST=0 ungates project-scope MCP. NOT .cursor/mcp.json (grok's cursor-compat is off). Measured 2026-09-15 on grok 0.2.93: an AMC-shaped project server listed as scope: project, doctor-handshook, and was called on a real --prompt-file turn (PONG_AMC_GROK_MCP). An empty control (no project .grok/) listed [].
• Images — an images turn delivers the prompt as ACP content blocks [{type:text},{type:image,data:<base64>,mimeType}] through --prompt-file (base64 in the file → argv-safe). Grok's schema is ACP, NOT Anthropic's source.{...} — top-level data + mimeType are required. Gated on capabilities.images so every other one-shot provider keeps its byte-identical text-path embed.
• Config isolation — Omniscio-spawned Grok runs as GROK, not the user's Claude/Cursor setup: GROK_CLAUDE_* / GROK_CURSOR_* _ENABLED=false. Grok does NOT execute ~/.claude hooks (verified), so no HOME isolation / worktree-neutralize is needed.
• Resume — turn 1 mints a randomUUID() + --session-id <uuid> (Grok echoes its id only on the end frame, so minting up front keeps an aborted-early first turn resumable); later turns pass --resume <id>.
• Security — --always-approve auto-approves every tool with no Omniscio-side approval net (Grok exposes no headless pre-exec approval hook) — identical to how Omniscio runs Claude (--dangerously-skip-permissions). Mitigated by the opt-in toggle (default off) + the Settings warning. See auto-approve-is-an-accepted-documented-risk.

Stream format

Flat NDJSON. A v1.x end frame additionally carries usage + total_cost_usd_ticks:

{"type":"thought","data":"<chunk>"}            → reasoning, streamed (liveness only, not rendered)
{"type":"text","data":"<chunk>"}               → the answer, streamed
{"type":"end","stopReason":"EndTurn","sessionId":"<uuid>","usage":{…},"total_cost_usd_ticks":N}  → terminal success
{"type":"error","message":"<text>"}            → terminal failure (logged raw, surfaced humanized)

No system/init, no tool_call frames. A 0.2.x end frame omits usage/cost (graceful degrade).

Skills — Grok reads your library directly

Grok needs no skill copying. Its Claude Code compatibility layer treats ~/.claude/skills as one of its own user-scope skill roots, so every skill you have is already available in a Grok session. Verified against grok 0.2.93 by dropping a probe SKILL.md into a throwaway home's .claude/skills and finding it in grok inspect --json — including with GROK_HOME redirected to an isolated directory, which is exactly what Omniscio does for a managed Grok account (that isolation moves ~/.grok, not your home folder, so skill discovery is unaffected).

Because of that, Grok is registered in Provider Config Sync with a native skills target: it appears as a sync target and receives the managed instructions block in ~/.grok/AGENTS.md, but no skill folder is ever copied to it, and its row reads already available.

Two consequences worth knowing:

• Grok gets no master-skills prompt index. Engines with no native skill surface receive a metadata-only list of every skill in the first message. Grok was wrongly on that list until 2026-09-02 and was being handed a ~12k-character index describing skills it already had. Registering it as native removed that redundancy.
• Grok's own built-in skills stay Grok's. ~/.grok/skills ships check-work, code-review, create-skill, docx, help, imagine, pptx, and xlsx. Omniscio never writes to that folder, and deliberately declares no ingest source there, so those built-ins are never pulled into your library or fanned out to Codex and Gemini.

If xAI ever drops Claude Code compatibility, this breaks silently — the registry entry carries a comment saying so, and the fix would be switching its skills target to global.

Files

• src/main/process/grok-turn-runner.ts — per-turn spawn, stream, resume, compat-off env, humanized errors, ACP image-block builder (buildGrokPromptPayload).
• src/main/process/grok-stream-translator.ts — the pure thought/text/end/error parser (v1.x usage + cost).
• src/main/services/engines/grok-cost.ts — priceGrokTurn (exact ticks or token-priced).
• src/main/services/engines/grok-binary-resolver.ts — resolves grok/grok.exe (PATH + ~/.grok/bin).
• src/main/services/engines/grok-credential-store.ts — grokApiKey (shared-xaiApiKey DRY fallback), hasGrokCliLogin, launchGrokSignIn.
• src/main/services/engines/grok-session-manager.ts — the one-shot manager config.
• src/main/services/provider-config-sync/provider-registry.ts — the grok sync entry (mcpMode: 'none', native skills target, ~/.grok/AGENTS.md).
• src/main/services/engines/grok-account-*.ts + src/main/db/queries-grok-accounts.ts — multi-account (isolated GROK_HOME, balancer, queries).
• src/main/services/providers/provider-mcp-connector.ts — the grok MCP connector (serializeGrokMcpServers).
• src/renderer/src/features/settings/sections/accounts/GrokAccountsTab.tsx + GrokAccountRow.tsx + components/ui/account/GrokAccountsPopoverTab.tsx + stores/slices/grok-account-slice.ts — the multi-account Settings UI + the account-popover mirror.

Comparison with other providers

	Grok	Cursor	Hermes
Runtime	one-shot-cli	one-shot-cli	one-shot-cli
Auth	account sign-in or xAI key	Cursor API key	none (own config)
Cost	estimated (usage + exact/priced $)	estimated (token-priced)	not reported
Images / vision	yes (ACP blocks via --prompt-file)	no	no
MCP	yes (native .grok/config.toml)	yes (.cursor/mcp.json)	no
Multi-account	yes (isolated GROK_HOME)	no	no
Tool markers	none	yes	none
.claude isolation	env toggles (no hooks run)	managed HOME + worktree-neutralize	n/a
Skills	native (reads ~/.claude/skills)	copied into .cursor/skills	no

Related

• Invariants: provider-registry-engines-more-grok-shot-cli-contract.md — a-switch-surface-is-registry-derived … this-engine-owns-its-first-output-deadline.
• switching-providers.md — the unified provider-switching guide.
• cursor-provider.md — the closest one-shot-cli sibling.
• codex-provider.md — the multi-account + account-auth sibling Grok's subsystem mirrors.