ouroboros-ai 0.44.1.dev3__tar.gz → 0.44.1.dev4__tar.gz

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.44.1.dev3
+Version: 0.44.1.dev4
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/docs/cli-reference.md

@@ -68,7 +68,7 @@ ouroboros auto "Build a local-first habit tracker CLI"
 | Option | Description |
 |--------|-------------|
 | `--resume TEXT` | Resume an existing auto session id |
-| `--runtime TEXT` | Runtime backend for the **run-handoff** phase. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`. Authoring phases (interview, seed generation, seed repair) **always run in-process** inside the Ouroboros MCP server in `ooo auto` flow — see [What `--runtime` controls in `ooo auto`](#what---runtime-controls-in-ooo-auto) below. |
+| `--runtime TEXT` | Runtime backend for the **run-handoff** phase. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`. Authoring phases (interview, seed generation, seed repair) **always run in-process** inside the Ouroboros MCP server in `ooo auto` flow — see [What `--runtime` controls in `ooo auto`](#what---runtime-controls-in-ooo-auto) below. |
 | `--max-interview-rounds INTEGER` | Maximum automatic interview rounds; prevents unbounded interview loops |
 | `--max-repair-rounds INTEGER` | Maximum Seed repair rounds; prevents unbounded repair loops |
 | `--skip-run` | Stop after creating an A-grade Seed |
@@ -243,7 +243,7 @@ ouroboros setup [OPTIONS]
 
 | Option | Description |
 |--------|-------------|
-| `-r, --runtime TEXT` | Runtime backend to configure. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`. Auto-detected if omitted |
+| `-r, --runtime TEXT` | Runtime backend to configure. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`. Auto-detected if omitted |
 | `--opencode-mode TEXT` | OpenCode integration mode: `plugin` (default, recommended — bridge plugin for interactive sessions) or `subprocess` (headless/CI). Mutually exclusive — see [OpenCode runtime guide](runtime-guides/opencode.md#configuration) |
 | `--non-interactive` | Skip interactive prompts (for scripted installs) |
 | `--mcp-mode TEXT` | Codex MCP config mode: `auto` (default), `preserve`, or `stdio` |
@@ -343,7 +343,7 @@ ouroboros init [start] [OPTIONS] [CONTEXT]
 | `-r, --resume TEXT` | Resume an existing interview by ID |
 | `--state-dir DIRECTORY` | Custom directory for interview state files |
 | `-o, --orchestrator` | Use Claude Code for the interview/seed flow; combine with `--runtime` to choose the workflow handoff backend |
-| `--runtime TEXT` | Agent runtime backend for the workflow execution step after seed generation. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`. Custom adapters registered in `runtime_factory.py` are also accepted. |
+| `--runtime TEXT` | Agent runtime backend for the workflow execution step after seed generation. Shipped values: `claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`. Custom adapters registered in `runtime_factory.py` are also accepted. |
 | `--llm-backend TEXT` | LLM backend for interview, ambiguity scoring, and seed generation (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`, `gjc`) |
 | `-d, --debug` | Show verbose logs including debug messages |
 
@@ -416,7 +416,7 @@ ouroboros run [workflow] [OPTIONS] SEED_FILE
 | Option | Description |
 |--------|-------------|
 | `-o/-O, --orchestrator/--no-orchestrator` | Use the agent-runtime orchestrator for execution (default: enabled) |
-| `--runtime TEXT` | Agent runtime backend override (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`). Uses configured default if omitted |
+| `--runtime TEXT` | Agent runtime backend override (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`, `grok`). Uses configured default if omitted |
 | `-r, --resume TEXT` | Resume a previous orchestrator session by ID |
 | `--mcp-config PATH` | Path to MCP client configuration YAML file |
 | `--mcp-tool-prefix TEXT` | Prefix to add to all MCP tool names (e.g., `mcp_`) |
@@ -945,7 +945,7 @@ ouroboros mcp serve [OPTIONS]
 | `-p, --port INTEGER` | Port to bind to (default: 8080) |
 | `-t, --transport TEXT` | Transport type: `stdio`, `sse`, or `streamable-http` (default: stdio). Note: `http` is only a client config alias for outbound MCP connections and is NOT a valid serve transport. |
 | `--db TEXT` | Path to the EventStore database file |
-| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`). Affects which tool variants are instantiated |
+| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`, `grok`). Affects which tool variants are instantiated |
 | `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`, `gjc`). Affects which tool variants are instantiated |
 
 **Examples:**
@@ -1027,7 +1027,7 @@ ouroboros mcp info [OPTIONS]
 
 | Option | Description |
 |--------|-------------|
-| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`). Affects which tool variants are instantiated |
+| `--runtime TEXT` | Agent runtime backend for orchestrator-driven tools (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `copilot`, `goose`, `kiro`, `pi`, `gjc`, `antigravity`, `grok`). Affects which tool variants are instantiated |
 | `--llm-backend TEXT` | LLM backend for interview/seed/evaluation tools (`claude_code`, `litellm`, `codex`, `copilot`, `opencode`, `gemini`, `goose`, `kiro`, `pi`, `gjc`). Affects which tool variants are instantiated |
 
 **Available Tools:**
@@ -1066,7 +1066,7 @@ The table below covers the most commonly used variables. For the full list — i
 | `ANTHROPIC_API_KEY` | — | Anthropic API key for Claude models |
 | `OPENAI_API_KEY` | — | OpenAI API key for LiteLLM / Codex CLI |
 | `OPENROUTER_API_KEY` | — | OpenRouter API key for consensus and LiteLLM |
-| `OUROBOROS_AGENT_RUNTIME` | `orchestrator.runtime_backend` | Override the runtime backend (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`) |
+| `OUROBOROS_AGENT_RUNTIME` | `orchestrator.runtime_backend` | Override the runtime backend (`claude`, `codex`, `opencode`, `hermes`, `gemini`, `goose`, `kiro`, `copilot`, `pi`, `gjc`, `antigravity`, `grok`) |
 | `OUROBOROS_RUNTIME` | `orchestrator.runtime_backend` (fallback) | Shortcut env var honored by both `orchestrator.runtime_backend` and `llm.backend` resolution when their dedicated env vars are unset |
 | `OUROBOROS_KIRO_CLI_PATH` | `orchestrator.kiro_cli_path` | Explicit path to `kiro-cli` binary when it is not on `PATH` |
 | `OUROBOROS_AGENT_PERMISSION_MODE` | `orchestrator.permission_mode` | Permission mode for Claude Code / Codex runtimes (no-op for OpenCode) |

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/docs/runtime-capability-matrix.md

@@ -13,7 +13,7 @@ The runtime backend is selected via the `orchestrator.runtime_backend` config ke
 
 ```yaml
 orchestrator:
-  runtime_backend: claude   # Supported values: claude | codex | opencode | hermes | gemini | kiro | copilot | pi | gjc | antigravity
+  runtime_backend: claude   # Supported values: claude | codex | opencode | hermes | gemini | kiro | copilot | pi | gjc | antigravity | grok
                             # The runtime abstraction layer also accepts custom
                             # adapters registered in runtime_factory.py
 ```
@@ -26,14 +26,15 @@ ouroboros run workflow --runtime codex seed.yaml
 
 You can also override the configured backend with the `OUROBOROS_AGENT_RUNTIME` environment variable.
 
-> **Extensibility:** Ouroboros uses a pluggable `AgentRuntime` protocol. Claude Code, Codex CLI, OpenCode, Hermes, Gemini CLI, Kiro CLI, GitHub Copilot CLI, Pi CLI, GJC, and the Antigravity CLI (`agy`, Google's Gemini-CLI successor — runtime-only) are the natively shipped backends; additional runtimes can be registered by implementing the protocol and extending `runtime_factory.py`. See [Architecture — How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter). For the full Antigravity contract, see [runtime-guides/antigravity.md](runtime-guides/antigravity.md).
+> **Extensibility:** Ouroboros uses a pluggable `AgentRuntime` protocol. Claude Code, Codex CLI, OpenCode, Hermes, Gemini CLI, Kiro CLI, GitHub Copilot CLI, Pi CLI, GJC, the Antigravity CLI (`agy`, Google's Gemini-CLI successor — runtime-only), and the Grok Build CLI (`grok`, xAI — runtime-only) are the natively shipped backends; additional runtimes can be registered by implementing the protocol and extending `runtime_factory.py`. See [Architecture — How to add a new runtime adapter](architecture.md#how-to-add-a-new-runtime-adapter). For the full contracts, see [runtime-guides/antigravity.md](runtime-guides/antigravity.md) and [runtime-guides/grok.md](runtime-guides/grok.md).
 
 ## Capability Matrix
 
 > **Note — runtime-only backends not yet threaded as columns:** The tables below
 > predate the runtime-only backends added more recently. Their per-capability
 > contract lives in the per-runtime guide rather than as a column here:
-> Antigravity (`agy`) → [runtime-guides/antigravity.md](runtime-guides/antigravity.md).
+> Antigravity (`agy`) → [runtime-guides/antigravity.md](runtime-guides/antigravity.md);
+> Grok (`grok`) → [runtime-guides/grok.md](runtime-guides/grok.md).
 
 ### Workflow Layer (identical across runtimes)
 

ouroboros_ai-0.44.1.dev4/docs/runtime-guides/grok.md

@@ -0,0 +1,145 @@
+# Grok Build CLI Runtime
+
+Run Ouroboros workflows on top of the locally installed xAI **Grok Build** CLI
+(the `grok` binary).
+
+The Grok runtime is a sibling of the Codex / Gemini / Hermes runtimes:
+Ouroboros owns the orchestration loop and shells out to `grok` per task. Grok
+emits a structured `streaming-json` event stream, so intermediate reasoning and
+output are surfaced live; v1 checkpoints at the Ouroboros layer (event store +
+lineage) rather than using Grok's native session resume.
+
+## Prerequisites
+
+| Requirement       | Why                                                              |
+|-------------------|------------------------------------------------------------------|
+| `grok` CLI        | Provider — install via `curl -fsSL https://x.ai/cli/install.sh \| bash` |
+| xAI auth          | `grok login` (browser OAuth, SuperGrok / X Premium+) or `XAI_API_KEY` |
+| Ouroboros (base)  | `pip install ouroboros-ai` — no provider-specific extras         |
+
+> Grok Build runs on the **base** Ouroboros package. It does **not** require the
+> `[claude]` extra.
+
+## Quick start
+
+```bash
+# 1. Install + authenticate the Grok Build CLI
+curl -fsSL https://x.ai/cli/install.sh | bash
+grok login                           # browser OAuth (SuperGrok / X Premium+)
+
+# 2. Point Ouroboros at Grok (config.yaml or the settings GUI)
+ouroboros config                     # GUI: set a stage's runtime to "grok"
+
+# 3. Run a workflow
+ouroboros run workflow seed.yaml --runtime grok
+```
+
+## CLI path resolution
+
+The runtime looks for the binary in this order:
+
+1. Constructor argument `cli_path=...`
+2. `OUROBOROS_GROK_CLI_PATH` environment variable
+3. `orchestrator.grok_cli_path` in `~/.ouroboros/config.yaml`
+4. `grok` on `$PATH`
+
+## Configuration
+
+```yaml
+# ~/.ouroboros/config.yaml
+orchestrator:
+  runtime_backend: grok
+  grok_cli_path: ~/.local/bin/grok    # optional; auto-detected
+```
+
+Grok is **runtime-only** — it drives the agentic orchestrator but is not
+registered as an LLM-completion backend, so it is not a valid `llm.backend`
+value. For completion-level diversity (consensus / role models), route xAI Grok
+through `litellm`/OpenRouter.
+
+### Per-stage routing
+
+Grok is a strong cross-vendor stage in a multi-LLM pipeline — for example, as a
+divergent reflect/unstuck stage distinct from the execute vendor:
+
+```yaml
+orchestrator:
+  runtime_backend: claude
+  runtime_profile:
+    stages:
+      execute: claude      # generate
+      evaluate: gemini     # cross-vendor verify
+      reflect: grok        # divergent lateral thinking
+```
+
+## Headless contract
+
+Each task spawns:
+
+```text
+grok -p <PROMPT> \
+     --output-format streaming-json \
+     --permission-mode acceptEdits \
+     [-m grok-build]
+```
+
+| Flag                  | Why                                                            |
+|-----------------------|----------------------------------------------------------------|
+| `-p`                  | Single-turn prompt; prints the response to stdout and exits    |
+| `--output-format`     | `streaming-json` NDJSON events parsed by the normalizer         |
+| `--permission-mode`   | Native non-blocking mode (`acceptEdits` / `bypassPermissions`)  |
+| `-m`                  | Optional model override (`grok-build`, `grok-composer-2.5-fast`)|
+
+Ouroboros maps its permission modes onto Grok's native `--permission-mode`:
+
+| Ouroboros permission mode | `grok` value        | When used                                |
+|---------------------------|---------------------|------------------------------------------|
+| `acceptEdits` (default)   | `acceptEdits`       | Applies edits without TTY prompts        |
+| `bypassPermissions`       | `bypassPermissions` | Explicit full bypass                     |
+
+The interactive Ouroboros `default` mode is normalized to `acceptEdits` (with an
+audit log) because a headless `grok -p` run cannot service a TTY approval
+prompt.
+
+Grok owns its own model catalog, so it is a **sentinel-model backend**:
+Ouroboros lets Grok pick its configured model and only forwards `-m` when you
+set an explicit id. The settings GUI **dynamically lists** the callable models
+by running `grok models` (parsing its bulleted output), so the picker reflects
+exactly what your Grok CLI / subscription can call; the static fallback catalog
+is `grok-build` and `grok-composer-2.5-fast`.
+
+## Event mapping
+
+The runtime parses Grok's `streaming-json` events through the shared NDJSON
+normalizer and maps them onto Ouroboros' `AgentMessage`:
+
+| Grok event                       | Ouroboros message                       |
+|----------------------------------|-----------------------------------------|
+| `{"type":"thought","data":...}`  | `assistant` with `data.thinking`        |
+| `{"type":"text","data":...}`     | `assistant` message                     |
+| `{"type":"end","stopReason":...}`| **terminal** `assistant` marker (`data.terminal=True`) |
+| `error`                          | `system` message with `data.is_error=True` |
+
+## Capabilities
+
+| Capability               | Status                                                |
+|--------------------------|-------------------------------------------------------|
+| Headless execution       | ✅ `grok -p`                                          |
+| Structured event stream  | ✅ `--output-format streaming-json`                   |
+| Tool calls               | ✅ (Grok-managed via `--permission-mode`)             |
+| Reasoning effort         | `grok --reasoning-effort` exists; native effort routing is a planned follow-up |
+| Session resumption       | ❌ not wired in v1 (`grok -r` exists; recovery at the Ouroboros lineage layer) |
+| LLM-completion backend   | ❌ runtime-only                                       |
+
+## Troubleshooting
+
+**`grok` not found.** Install the Grok Build CLI, then set
+`OUROBOROS_GROK_CLI_PATH=/abs/path/to/grok` or `orchestrator.grok_cli_path`.
+
+**Authentication errors.** Run `grok login` once (SuperGrok / X Premium+), or
+export `XAI_API_KEY` for headless/API-key use.
+
+**The CLI hangs waiting for input.** The runtime always passes `-p` and a
+non-blocking `--permission-mode`. If you see a hang, confirm you are invoking
+the runtime through `ouroboros run` (or the MCP server) rather than driving
+`grok` directly.

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/docs/runtime-guides/skill-capability-guides.md

@@ -43,6 +43,7 @@ its rendered guide or a documented fallback.
 | Copilot | `~/.copilot/ouroboros-instructions/AGENTS.md` | Installed by Copilot setup; Ouroboros Copilot runtime also injects that directory through `COPILOT_CUSTOM_INSTRUCTIONS_DIRS`. |
 | GJC | `<agent-dir>/rules/ouroboros-skill-capability-guide.md` | Installed by GJC setup as a setup-owned, renderer-generated capability artifact. |
 | Antigravity | No setup-owned capability artifact yet | Known gap: Antigravity (the `agy` binary, Google's Gemini CLI successor) can be selected as a runtime, but setup does not yet install a durable agy-owned instruction artifact. Use `render_backend_skill_capability_guide("antigravity")` when building Antigravity prompts until a stable artifact surface exists. |
+| Grok | No setup-owned capability artifact yet | Known gap: Grok Build (the `grok` binary) can be selected as a runtime, but setup does not yet install a durable grok-owned instruction artifact. Use `render_backend_skill_capability_guide("grok")` when building Grok prompts until a stable artifact surface exists. |
 | Goose | No setup-owned capability artifact yet | Known gap: setup can select Goose as a runtime, but no durable Goose instruction surface or Goose-specific `SkillExecutionCapability` entries are registered yet. Keep skill requirements runtime-neutral and rely on runtime-local operator guidance until a Goose artifact installer exists. |
 | Pi | No setup-owned capability artifact yet | Known gap: Pi has generic rendered capability guidance in the registry, but setup does not yet install it into a durable Pi-owned instruction artifact. Use `render_backend_skill_capability_guide("pi")` when building Pi prompts until a stable artifact surface exists. |
 

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.44.1.dev3'
-__version_tuple__ = version_tuple = (0, 44, 1, 'dev3')
+__version__ = version = '0.44.1.dev4'
+__version_tuple__ = version_tuple = (0, 44, 1, 'dev4')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/backends/capabilities.py

@@ -509,6 +509,23 @@ _CAPABILITIES: tuple[BackendCapability, ...] = (
         supports_tool_envelope=False,
         skill_execution_capabilities=_GENERIC_SKILL_EXECUTION_CAPABILITIES,
     ),
+    BackendCapability(
+        # Grok Build (xAI) — the ``grok`` binary. Runtime-only: ``grok -p
+        # --output-format streaming-json`` drives the agentic orchestrator
+        # runtime. Auth is subscription OAuth (``grok login`` with SuperGrok /
+        # X Premium+) or ``XAI_API_KEY``. Grok owns its own model catalog
+        # (``grok models``), so it is a sentinel-model backend.
+        name="grok",
+        aliases=("grok_cli", "grok_build"),
+        supports_runtime=True,
+        supports_llm=False,
+        supports_interview_driver=False,
+        switchable_runtime=True,
+        cli_name="grok",
+        cli_config_key="grok_cli_path",
+        supports_tool_envelope=False,
+        skill_execution_capabilities=_GENERIC_SKILL_EXECUTION_CAPABILITIES,
+    ),
     BackendCapability(
         # ourocode is an LLM-completion backend only: it streams a single Claude
         # turn over ACP (`ourocode --acp`, its OAuth `:claude_api`) with no tool

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/backends/model_catalog.py

@@ -21,6 +21,7 @@ because ``opencode models`` has been verified; other backends degrade to
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
 import shutil
@@ -36,7 +37,7 @@ from ouroboros.config._model_defaults import DEFAULT_OPUS_MODEL, DEFAULT_SONNET_
 # than a Claude model id. Mirrors the loader's sentinel frozensets
 # (_CODEX_LLM_BACKENDS et al.); the mirror is locked by a unit test.
 _SENTINEL_MODEL_BACKENDS = frozenset(
-    {"codex", "opencode", "kiro", "copilot", "hermes", "pi", "gjc", "antigravity"}
+    {"codex", "opencode", "kiro", "copilot", "hermes", "pi", "gjc", "antigravity", "grok"}
 )
 
 # The sentinel the loader maps Claude-incapable backends to.
@@ -78,11 +79,63 @@ class BackendModelCatalog:
 _EXTRA_KNOWN_MODELS: dict[str, tuple[str, ...]] = {
     "claude": ("claude-haiku-4-5-20251001",),
     "codex": ("gpt-5-codex", "gpt-5", "gpt-5-mini"),
+    # Grok Build model slugs, after the CLI-owned "default" sentinel. Verified
+    # against a live `grok models` listing (grok-build, grok-composer-2.5-fast).
+    "grok": ("grok-build", "grok-composer-2.5-fast"),
 }
 
-# Verified model-listing subcommands (one model id per line on stdout).
+# Verified model-listing subcommands. The resolved backend binary is invoked
+# with these args and the stdout is parsed by the backend's entry in
+# `_LIST_PARSERS` (default: one model id per line).
 _LIST_ARGS: dict[str, tuple[str, ...]] = {
     "opencode": ("models",),
+    "grok": ("models",),
+}
+
+
+def _parse_models_one_per_line(stdout: str) -> tuple[str, ...]:
+    """Default listing parser: one model id per non-blank line."""
+    return tuple(line.strip() for line in stdout.splitlines() if line.strip())
+
+
+def _parse_grok_models(stdout: str) -> tuple[str, ...]:
+    """Parse ``grok models`` output into callable model ids.
+
+    Grok prints auth / default-model headers and a bulleted "Available models"
+    list rather than one id per line, e.g.::
+
+        You are logged in with grok.com.
+
+        Default model: grok-composer-2.5-fast
+
+        Available models:
+          - grok-build
+          * grok-composer-2.5-fast (default)
+
+    Extract the bulleted ids (dropping the ``-``/``*`` bullet and any trailing
+    ``(default)`` marker), preserving order and de-duplicating, so the catalog
+    reflects exactly what the user's Grok CLI can call.
+    """
+    models: list[str] = []
+    in_list = False
+    for line in stdout.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.lower().startswith("available models"):
+            in_list = True
+            continue
+        if in_list and stripped[0] in "-*":
+            parts = stripped[1:].strip().split()
+            if parts:
+                models.append(parts[0])
+    return tuple(dict.fromkeys(models))
+
+
+# Backend-specific stdout parsers for `refresh_models`. Backends absent here use
+# `_parse_models_one_per_line`.
+_LIST_PARSERS: dict[str, Callable[[str], tuple[str, ...]]] = {
+    "grok": _parse_grok_models,
 }
 
 
@@ -166,7 +219,8 @@ def refresh_models(
         )
     except (OSError, subprocess.SubprocessError):
         return None
-    models = tuple(line.strip() for line in result.stdout.splitlines() if line.strip())
+    parser = _LIST_PARSERS.get(catalog.backend, _parse_models_one_per_line)
+    models = parser(result.stdout)
     return models or None
 
 
@@ -184,6 +238,7 @@ _CLI_PATH_GETTERS: dict[str, str] = {
     "pi": "get_pi_cli_path",
     "gjc": "get_gjc_cli_path",
     "antigravity": "get_antigravity_cli_path",
+    "grok": "get_grok_cli_path",
     "ourocode": "get_ourocode_cli_path",
 }
 

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/cli/commands/auto.py

@@ -110,6 +110,7 @@ class AgentRuntimeBackend(str, Enum):  # noqa: UP042
     PI = "pi"
     GJC = "gjc"
     ANTIGRAVITY = "antigravity"
+    GROK = "grok"
 
 
 app = typer.Typer(

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/cli/commands/config.py

@@ -466,6 +466,10 @@ def backend(
         from ouroboros.config import get_antigravity_cli_path
 
         cli_path = get_antigravity_cli_path()
+    elif new_backend == "grok":
+        from ouroboros.config import get_grok_cli_path
+
+        cli_path = get_grok_cli_path()
     if not cli_path:
         cli_path = shutil.which(cli_name)
     if not cli_path:
@@ -510,6 +514,7 @@ def backend(
         _setup_gemini,
         _setup_gjc,
         _setup_goose,
+        _setup_grok,
         _setup_hermes,
         _setup_pi,
     )
@@ -543,6 +548,8 @@ def backend(
             _setup_pi(cli_path)
         elif new_backend == "antigravity":
             _setup_antigravity(cli_path)
+        elif new_backend == "grok":
+            _setup_grok(cli_path)
     except Exception as exc:
         setup_failed = True
         console.quiet = prev_quiet

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/cli/commands/init.py

@@ -73,6 +73,7 @@ class AgentRuntimeBackend(str, Enum):  # noqa: UP042
     PI = "pi"
     GJC = "gjc"
     ANTIGRAVITY = "antigravity"
+    GROK = "grok"
 
 
 class LLMBackend(str, Enum):  # noqa: UP042

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/cli/commands/mcp.py

@@ -72,6 +72,7 @@ class AgentRuntimeBackend(str, Enum):  # noqa: UP042
     PI = "pi"
     GJC = "gjc"
     ANTIGRAVITY = "antigravity"
+    GROK = "grok"
 
 
 class LLMBackend(str, Enum):  # noqa: UP042

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/cli/commands/run.py

@@ -123,6 +123,7 @@ class AgentRuntimeBackend(str, Enum):  # noqa: UP042
     PI = "pi"
     GJC = "gjc"
     ANTIGRAVITY = "antigravity"
+    GROK = "grok"
 
 
 def _derive_quality_bar(seed: "Seed") -> str:

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/cli/commands/setup.py

@@ -255,6 +255,15 @@ def _detect_runtimes() -> dict[str, str | None]:
         antigravity_path = None
     runtimes["antigravity"] = antigravity_path or shutil.which("agy")
 
+    # Grok Build (grok): explicit-path config first, then PATH.
+    try:
+        from ouroboros.config import get_grok_cli_path
+
+        grok_path = get_grok_cli_path()
+    except Exception:
+        grok_path = None
+    runtimes["grok"] = grok_path or shutil.which("grok")
+
     return runtimes
 
 
@@ -2167,6 +2176,11 @@ def _setup_antigravity(antigravity_path: str) -> None:
     _setup_runtime_only_backend("antigravity", antigravity_path, "antigravity_cli_path")
 
 
+def _setup_grok(grok_path: str) -> None:
+    """Configure Ouroboros for the Grok Build CLI (``grok``) runtime."""
+    _setup_runtime_only_backend("grok", grok_path, "grok_cli_path")
+
+
 def _setup_pi(pi_path: str) -> None:
     """Configure Ouroboros for the Pi CLI runtime.
 
@@ -3236,6 +3250,16 @@ def setup(
             )
             raise typer.Exit(1)
         _setup_antigravity(antigravity_path)
+    elif selected in ("grok", "grok_cli", "grok_build"):
+        grok_path = available.get("grok")
+        if not grok_path:
+            print_error(
+                "Grok Build CLI (grok) not found.\n"
+                "Install it (curl -fsSL https://x.ai/cli/install.sh | bash), set "
+                "OUROBOROS_GROK_CLI_PATH, or configure orchestrator.grok_cli_path."
+            )
+            raise typer.Exit(1)
+        _setup_grok(grok_path)
     else:
         print_error(f"Unsupported runtime: {selected}")
         raise typer.Exit(1)

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/config/__init__.py

@@ -46,6 +46,7 @@ from ouroboros.config.loader import (
     get_gemini_cli_path,
     get_gjc_cli_path,
     get_goose_cli_path,
+    get_grok_cli_path,
     get_hermes_cli_path,
     get_kiro_cli_path,
     get_llm_backend,
@@ -154,6 +155,7 @@ __all__ = [
     "get_gemini_cli_path",
     "get_gjc_cli_path",
     "get_goose_cli_path",
+    "get_grok_cli_path",
     "get_hermes_cli_path",
     "get_kiro_cli_path",
     "get_opencode_cli_path",

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/config/loader.py

@@ -82,6 +82,10 @@ _GJC_LLM_BACKENDS = frozenset({"gjc", "gjc_cli"})
 # configured default (the "default" sentinel), exactly like the other
 # non-Claude CLI backends above.
 _ANTIGRAVITY_LLM_BACKENDS = frozenset({"antigravity", "agy"})
+# Grok Build (`grok`) is runtime-only and Claude-incapable: it runs xAI's own
+# Grok models, so generic Claude default ids map to the CLI's own configured
+# default (the "default" sentinel).
+_GROK_LLM_BACKENDS = frozenset({"grok", "grok_cli", "grok_build"})
 _OPENCODE_BACKENDS = frozenset({"opencode", "opencode_cli"})
 _CODEX_DEFAULT_MODEL = "default"
 _KIRO_DEFAULT_MODEL = "default"
@@ -90,6 +94,7 @@ _HERMES_DEFAULT_MODEL = "default"
 _PI_DEFAULT_MODEL = "default"
 _GJC_DEFAULT_MODEL = "default"
 _ANTIGRAVITY_DEFAULT_MODEL = "default"
+_GROK_DEFAULT_MODEL = "default"
 _PLACEHOLDER_API_KEY_PREFIX = "YOUR_"
 _PLACEHOLDER_API_KEY_SUFFIX = "_API_KEY"
 _DEFAULT_MAX_PARALLEL_WORKERS = 3
@@ -176,6 +181,7 @@ _UNTRUSTED_ENV_DENYLIST = frozenset(
         "OUROBOROS_PI_CLI_PATH",
         "OUROBOROS_GJC_CLI_PATH",
         "OUROBOROS_ANTIGRAVITY_CLI_PATH",
+        "OUROBOROS_GROK_CLI_PATH",
         "OUROBOROS_OUROCODE_CLI_PATH",
         # Bare provider aliases (no OUROBOROS_ prefix) that adapters also
         # honor and then execute. Any new such alias MUST be added here:
@@ -1423,6 +1429,41 @@ def get_antigravity_cli_path() -> str | None:
     return None
 
 
+def get_grok_cli_path() -> str | None:
+    """Get the Grok Build CLI path (``grok``) from environment or config.
+
+    Priority:
+        1. OUROBOROS_GROK_CLI_PATH environment variable
+        2. config.yaml orchestrator.grok_cli_path
+        3. None (resolve from PATH at runtime)
+
+    Stale env var / config values that don't point to an executable are
+    treated as missing so callers fall back to PATH discovery instead of
+    persisting an unusable path. Mirrors the strictness of `shutil.which`
+    used for the other runtime backends in the setup detection path.
+
+    Returns:
+        Path to the Grok Build CLI binary or None.
+    """
+    env_path = os.environ.get("OUROBOROS_GROK_CLI_PATH", "").strip()
+    if env_path:
+        resolved = str(Path(env_path).expanduser())
+        if shutil.which(resolved):
+            return resolved
+
+    try:
+        config = load_config()
+        grok_path = getattr(config.orchestrator, "grok_cli_path", None)
+        if grok_path:
+            resolved = str(Path(grok_path).expanduser())
+            if shutil.which(resolved):
+                return resolved
+    except ConfigError:
+        pass
+
+    return None
+
+
 def get_llm_backend() -> str:
     """Get default LLM backend from environment variable or config.
 
@@ -1779,6 +1820,8 @@ def _default_model_for_backend(
         return _GJC_DEFAULT_MODEL
     if resolved in _ANTIGRAVITY_LLM_BACKENDS:
         return _ANTIGRAVITY_DEFAULT_MODEL
+    if resolved in _GROK_LLM_BACKENDS:
+        return _GROK_DEFAULT_MODEL
     return default_model
 
 
@@ -1827,6 +1870,8 @@ def _normalize_configured_model_for_backend(
         return _GJC_DEFAULT_MODEL
     if resolved in _ANTIGRAVITY_LLM_BACKENDS and is_shipped_default:
         return _ANTIGRAVITY_DEFAULT_MODEL
+    if resolved in _GROK_LLM_BACKENDS and is_shipped_default:
+        return _GROK_DEFAULT_MODEL
 
     return candidate
 

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/config/models.py

@@ -375,6 +375,9 @@ VALID_RUNTIME_BACKENDS = frozenset(
         "gjc_cli",
         "antigravity",
         "agy",
+        "grok",
+        "grok_cli",
+        "grok_build",
     }
 )
 
@@ -494,6 +497,10 @@ class OrchestratorConfig(BaseModel, frozen=True):
             - Absolute path: /path/to/agy
             - ~ expansion: ~/.local/bin/agy
             - None: Resolve from PATH at runtime (or OUROBOROS_ANTIGRAVITY_CLI_PATH)
+        grok_cli_path: Path to the Grok Build CLI binary (``grok``). Supports:
+            - Absolute path: /path/to/grok
+            - ~ expansion: ~/.local/bin/grok
+            - None: Resolve from PATH at runtime (or OUROBOROS_GROK_CLI_PATH)
         default_max_turns: Default max turns for agent execution
         max_parallel_workers: Default maximum concurrent AC workers
         usage_limit_pause_hours: Default pause window for provider usage/quota limits
@@ -515,6 +522,7 @@ class OrchestratorConfig(BaseModel, frozen=True):
         "pi",
         "gjc",
         "antigravity",
+        "grok",
     ] = "claude"
     runtime_profile: RuntimeProfileConfig | None = None
 
@@ -554,6 +562,7 @@ class OrchestratorConfig(BaseModel, frozen=True):
     pi_cli_path: str | None = None
     gjc_cli_path: str | None = None
     antigravity_cli_path: str | None = None
+    grok_cli_path: str | None = None
     ourocode_cli_path: str | None = None
     default_max_turns: int = Field(default=10, ge=1)
     max_parallel_workers: int = Field(default=3, ge=1)
@@ -575,6 +584,7 @@ class OrchestratorConfig(BaseModel, frozen=True):
         "pi_cli_path",
         "gjc_cli_path",
         "antigravity_cli_path",
+        "grok_cli_path",
         "ourocode_cli_path",
     )
     @classmethod

{ouroboros_ai-0.44.1.dev3 → ouroboros_ai-0.44.1.dev4}/src/ouroboros/orchestrator/backend_limits.py

@@ -105,6 +105,7 @@ _BACKEND_ALIASES = {
     "copilot_cli": "copilot",
     "opencode_cli": "opencode",
     "antigravity_cli": "antigravity",
+    "grok_cli": "grok",
 }
 
 # Backends with Ouroboros-known governance. Only the native Claude adapter is