xAI & Grok Provider
Relevant source files
The following files were used as context for generating this wiki page:
The xAI and Grok provider integration in shunt allows users to divert Claude Code LLM requests to xAI's infrastructure. While often used interchangeably in casual conversation, shunt maintains a technical distinction between the xAI API (metered developer access via API keys) and the Grok subscription (access via OAuth linked to X Premium+/SuperGrok subscriptions). Both integrations utilize the responses adapter kind to translate Anthropic Messages into the OpenAI-compatible Responses API format.
Sources: README.md:14-25, blueprints/upstream/xai.md:73-77, ARCHITECTURE.md:17-25
Provider Architecture
The xAI and Grok providers are implemented using the responses adapter, which handles the translation of Anthropic-style requests into the format expected by xAI's endpoints. The system ensures that streaming semantics are preserved, forwarding server-sent events (SSE) to the client without buffering unless non-streaming output is explicitly requested.
Data Flow Overview
When a request targeting an xAI or Grok model is received, the gateway buffers the inbound body, resolves the route, injects the appropriate credentials (API Key or OAuth token), and dispatches the request to the upstream xAI environment.
The diagram shows the request path from the client through the shunt gateway, selecting between the metered xAI API and the subscription-based Grok proxy.
Sources: ARCHITECTURE.md:82-95, blueprints/upstream/xai.md:20-25
xAI vs. Grok Configuration
shunt treats the metered API and the subscription proxy as separate entities with different billing models and authentication mechanisms.
| Feature | xAI Provider | Grok Provider |
|---|---|---|
| Backend URL | https://api.x.ai/v1 | https://cli-chat-proxy.grok.com/v1 |
| Auth Mode | XAI_API_KEY (Metered) | xai_oauth (Subscription) |
| Credential File | N/A (Environment variable) | ~/.shunt/xai-auth.json |
| Login Command | N/A | shunt login xai |
| Primary Use | Developer API / Token-based | X Premium+ / SuperGrok users |
Sources: README.md:120-135, blueprints/upstream/xai.md:73-77
Metered xAI API Setup
The xAI API upstream uses a metered billing model. Users must provide an API key via environment variables.
[[upstreams]]
name = "xai"
provider = "xai" # Uses preset: kind="responses", auth="api_key"
Sources: blueprints/upstream/xai.md:20-25, ARCHITECTURE.md:135
Grok Subscription Setup
The grok provider allows users to reuse existing X Premium+ or SuperGrok subscriptions. Authentication is handled via an OAuth flow initiated by the CLI.
# Authenticate the Grok subscription
shunt login xai
Sources: README.md:120-135, ARCHITECTURE.md:135
Supported Models and Agents
The xAI/Grok provider supports several model tiers. Specific agents are defined in the project to leverage these models within the Claude Code harness.
Model Identifiers
Common model slugs used in configuration include:
grok-4.5grok-4.3grok-build-0.1(Flagship coding model)
Sources: plugins/shunt-xai/agents/grok-4.5.md:5-10, plugins/shunt-xai/agents/grok-build-0.1.md:5-10, blueprints/upstream/xai.md:38-45
Agent Capabilities
The grok-build-0.1 agent is specifically tuned for engineering tasks, including searching codebases, analyzing architecture, and performing multi-step research. It is configured to run through the shunt gateway while maintaining the tools available in the Claude Code environment.
Sources: plugins/shunt-xai/agents/grok-build-0.1.md:12-25
Implementation Details
The integration is built upon the Adapter trait. Key architectural invariants ensure that the provider remains robust:
- Reasoning Effort: Many Grok models reject
reasoning.effortparameters unless explicitly configured or opted-in via specific model versions. - Error Reshaping: Upstream errors from xAI (e.g., 429 Rate Limit or 403 Forbidden) are reshaped into the Anthropic error envelope before being returned to the client.
- Experimental Status: The provider is currently marked as experimental and may require verification against live API behavior for specific reasoning capabilities.
Sources: plugins/shunt-xai/agents/grok-4.5.md:5-10, ARCHITECTURE.md:166-173, blueprints/provider/_generic.md:46-52
Sequential Authentication Flow
The following sequence diagram illustrates the authentication and request dispatch for a Grok subscription:
Sources: README.md:120-135, ARCHITECTURE.md:40-52
Summary
The xAI & Grok provider integration enables flexible model switching for Claude Code users, providing a bridge to xAI's flagship models like Grok 4.5 and Grok-build. By separating metered API access from subscription-based proxying, shunt allows developers to optimize for either cost or convenience while maintaining a consistent tool-augmented engineering environment.
Sources: README.md:275-285, blueprints/upstream/xai.md:73-77