> ## Documentation Index
> Fetch the complete documentation index at: https://lab.pollack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Reference

> Complete configuration reference for the xAI Grok agent provider

## Overview

The Grok agent wraps the [xAI Grok CLI](https://grok.com/cli) via `GrokAgentModel`. Configure it through Spring properties under `agent-client.grok.*`.

```yaml theme={null}
agent-client:
  grok:
    model: grok-4.6
    reasoning-effort: high
    timeout: PT10M
```

## Configuration Properties

Prefix: `agent-client.grok`

| Property | Type | Default | Description |
| - | - | - | - |
| `mode` | `AgentClientMode` | — | Controls default permissiveness. Inherits from `agent-client.mode` if not set (default: `LOOSE`). |
| `model` | `String` | `grok-4.6` | Model to use (`--model`) |
| `reasoning-effort` | `String` | — | Reasoning effort (`--reasoning-effort`): `low`, `medium`, `high`. The portable `effort` values map here directly. |
| `timeout` | `Duration` | `5m` | Timeout for agent task execution |
| `permission-mode` | `PermissionMode` | — | `--permission-mode`. When not explicitly set, derived from mode (see below). |
| `max-turns` | `Integer` | — | Maximum agent turns (`--max-turns`) |
| `disable-web-search` | `boolean` | `false` | Disable web search and fetch tools (`--disable-web-search`) |
| `executable-path` | `String` | — | Path to the Grok CLI executable (auto-discovered if not set) |

## permissionMode and Mode Interaction

| `permission-mode` | `mode` | Effective Value | Behavior |
| - | - | - | - |
| explicit | any | as set | Always wins |
| unset | `STRICT` | `default` | The CLI's own default — a tool call needing approval stops the run |
| unset | `LOOSE` | `bypassPermissions` | Every tool call is approved without prompting |

The portable `isAutoApprove()` maps to `bypassPermissions`, the only mode that grants every tool call without a prompt.

## Portable Option Mapping

| Portable option | Grok flag |
| - | - |
| `getModel()` | `--model` |
| `getEffort()` | `--reasoning-effort` (direct passthrough — `low`/`medium`/`high` are all valid) |
| `getMaxTurns()` | `--max-turns` |
| `getJsonSchema()` | `--json-schema` (serialized inline; no temp file) |
| `isAutoApprove()` | `--permission-mode bypassPermissions` |
| `getTimeout()` | process timeout |
| `getWorkingDirectory()` | `--cwd` and the process working directory |
| `getSystemInstructions()` | prepended to the goal — see below |

### System instructions are prepended, not passed as a flag

Grok has `--system-prompt-override`, but it *replaces* the CLI's own system prompt rather than adding to it, which strips the agent's tool instructions. Portable `systemInstructions` mean "also tell it this", so they are prepended to the goal — the same choice every other provider here makes.

## Result Metadata

Grok returns a JSON envelope in headless mode, so nothing is scraped from log text. `AgentResponseMetadata.getProviderFields()` carries:

| Field | Notes |
| - | - |
| `costUsd` | **A real per-run cost.** Grok is the only CLI in this family that reports one, so callers do not need a price table. |
| `inputTokens`, `outputTokens`, `thinkingTokens` | From the envelope's `usage` block |
| `cacheReadTokens`, `cacheCreationTokens`, `totalTokens` | |
| `numTurns`, `stopReason`, `exitCode`, `successful` | |
| `structured` | `false` when the output was not the expected envelope; the raw text is preserved as the response |

`getModel()` reports the model that actually ran (from the envelope's `modelUsage` key), which may differ from the requested slug when the CLI expands an alias. `getSessionId()` carries the session UUID.

## Sessions

Grok accepts a caller-supplied session UUID (`--session-id`) for a new conversation and resumes with `--resume <id>`, so the id never has to be recovered from output. `GrokClient.resume(sessionId, prompt, options)` exposes this. Grok does not currently implement `AgentSessionRegistry`.

<Note>
  `grok models` reports "You are not authenticated" even on an authenticated install. The provider's health check therefore uses `grok --version`; using `models` would reject a working CLI.
</Note>

## Availability

Since **0.28.0**.

## Installation

Install the CLI from [grok.com/cli](https://grok.com/cli) and authenticate once with `grok login`. The provider discovers the executable via `GROK_CLI_PATH`, then `which grok`, then `~/.local/bin/grok` and `~/.grok/bin/grok`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.