--- title: Grok Provider --- # 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 `/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](account-indicator.md#grok-accounts-tab-managed-account-mirror)). 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](codex-provider.md#how-omniscio-keeps-the-logins-separate-isolated-codex_home). ## How it behaves ### Choosing the model `grok -m ` 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 --output-format streaming-json --always-approve --cwd [-m ] [--session-id | --resume ]`. 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 `/.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:,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 ` (Grok echoes its id only on the `end` frame, so minting up front keeps an aborted-early first turn resumable); later turns pass `--resume `. - **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":""} → reasoning, streamed (liveness only, not rendered) {"type":"text","data":""} → the answer, streamed {"type":"end","stopReason":"EndTurn","sessionId":"","usage":{…},"total_cost_usd_ticks":N} → terminal success {"type":"error","message":""} → 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](provider-config-sync.md) 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](../../.claude/memory/contracts/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](switching-providers.md) — the unified provider-switching guide. - [cursor-provider.md](cursor-provider.md) — the closest one-shot-cli sibling. - [codex-provider.md](codex-provider.md) — the multi-account + account-auth sibling Grok's subsystem mirrors.