open-grok-build

OpenCode plugin that connects xAI's Grok Build models (cli-chat-proxy.grok.com) to your terminal. Ships OAuth 2.0 + PKCE authentication, a curated model catalog, payload sanitization for xAI API quirks, and live billing queries — all as a drop-in plugin.

Features

• OAuth 2.0 + PKCE — Browser-based login via auth.x.ai with automatic token refresh
• Model catalog — Six Grok Build models with correct cost, context window, and reasoning metadata
• Payload sanitization — Transparent rewrites for xAI's Responses API quirks (reasoning strip, image normalization, system→instructions, response_format→text.format, and more)
• Billing usage — /grok-build-usage slash command shows live credit quota as a TUI toast (no LLM turn consumed)

Quick Start

1. Install

opencode plugin -g open-grok-build

This registers both the server plugin (models, OAuth, payload sanitization) and the TUI plugin (/grok-build-usage slash command). Restart the TUI after installing.

2. Connect

/connect grok-build → Grok Build (cli-chat-proxy)

Or set GROK_BUILD_OAUTH_TOKEN for a static token bypass (no auto-refresh).

Local checkout

For development, use an absolute path:

{
  "plugin": ["/path/to/open-grok-build"]
}

Models

Model	Context	Max Output	Reasoning	Input
grok-composer-2.5-fast	200K	30K	—	text, image
grok-build	512K	30K	✓	text, image
grok-4.3	1M	30K	✓	text, image
grok-4.20-0309-reasoning	2M	30K	✓	text, image
grok-4.20-0309-non-reasoning	2M	30K	—	text, image
grok-4.20-multi-agent-0309	2M	30K	✓	text, image

Override with GROK_BUILD_MODELS (comma-separated model IDs). Unknown IDs get sensible defaults.

Payload Sanitization

The plugin transparently rewrites outgoing requests to handle xAI's Responses API differences from stock OpenAI:

• Strips replayed reasoning items (cause 400 errors on xAI)
• Drops empty-string content items
• Moves role: "developer" / role: "system" messages to top-level instructions
• Converts image_url parts to input_image with data URIs
• Resolves local image paths (.jpg, .jpeg, .png) to base64 — workspace-scoped for security
• Extracts images from function_call_output.output arrays into separate user messages
• Maps response_format → text.format
• Adds prompt_cache_key for session-affinity caching
• Normalizes reasoning.effort for models that support it

Environment Variables

Variable	Default	Description
GROK_BUILD_BASE_URL	https://cli-chat-proxy.grok.com/v1	API base URL
GROK_BUILD_MODELS	(catalog)	Comma-separated model IDs to expose
GROK_BUILD_OAUTH_CLIENT_ID	(built-in)	OAuth client ID override
GROK_BUILD_CALLBACK_HOST	127.0.0.1	OAuth loopback callback host
GROK_BUILD_CALLBACK_PORT	56122	OAuth loopback callback port
GROK_BUILD_OAUTH_TOKEN	—	Static token bypass (skips OAuth, no refresh)
GROK_BUILD_TOKEN_TIMEOUT_MS	30000	Timeout for OAuth token requests

Development

bun install
bun run check        # lint + typecheck + knip + duplicate check + coverage
bun run test         # tests only
bun run typecheck    # tsc --noEmit
bun run coverage     # tests with coverage

License

MIT