Grok Provider
xAI's Grok Build CLI as an alternative session provider — a different agent and a different model, not Claude in a different harness. How to enable it, which models you get, the readiness gaps, and how it reads your skills library.
On this page
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
grok0.2.x. Live measurement on grok 0.2.93 shows ACP image blocks andgrok mcpalready work —capabilities.imagesandcapabilities.mcpstay staticallytrueand 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 theendframe. A 0.2.xendwith no usage degrades on wire shape (usage: undefined→ "cost not reported"), not on a version probe. CONFIRMED (measured against grok 0.2.93):{"type":"end","stopReason":"EndTurn",…}— nousageblock, 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-jsonemits per-token text deltas. Grok also streams its reasoning asthoughtframes; Omniscio consumes those as liveness (feeding the no-first-output watchdog during a silent reasoning phase) and never renders them as the answer. - One
▸tool chip per call, like Claude. A v1.x turn streamstool_call/tool_call_updateframes: eachtool_callbecomes exactly ONE▸ Read: foo.tsline in the transcript (the same marker and label rule Gemini/Antigravity use), and atool_call_updatenever adds a second one — it only closes the call's structured record with its raw output. Those records carry name, raw input, raw output, failure flag and timing, so the Trajectory lists every tool the turn ran. The two halves are separate events: the marker is display, the record is the trajectory's. A 0.2.x CLI sends notool_callframes; it narrates its tool use in reasoning and records nothing. - 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 opt-in (like every alternative provider):
- Master toggle — Settings → Accounts → "Show alternative AI providers" — already ON on a fresh install, so the provider section is visible from the start (a profile that last saved before 3 Oct 2026 keeps the old Claude-only view until you turn it on). Turning it OFF hides every alternative provider.
- Install the CLI — click Install Grok CLI on the Settings → Accounts → Grok card, or run xAI's installer yourself:
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). On Windows the button runs that script under Git for Windows' ownbash, by full path — a barebashthere is the Windows Linux launcher, not Git Bash, so the install would otherwise fail or land inside the Linux side where Omniscio can never see it. If the card reports the prerequisite missing, install Git for Windows. - 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 loginin 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 rungrok loginin 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 dedicatedgrokApiKeyoverrides 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. Click Install Grok CLI on the card (or run xAI's installer yourself from x.ai/cli), then click Recheck; if still missing right after a fresh install, restart Omniscio.
- "Couldn't run the Grok installer. It needs bash and curl available…" — the installer never started because there is no shell to run it with. On Windows that means Git for Windows isn't installed; install it, or run the installer manually from x.ai/cli.
- "The Grok installer didn't finish." — it started and xAI's script failed, usually a dropped connection. Retry, or install Grok manually from x.ai/cli.
- "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").
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.
Last verified 2026-10-12