Grok Build Auth Plugin for OpenCode

OpenCode plugin that authenticates with Grok Build and Composer 2.5 models through the same cli-chat-proxy backend used by the Grok CLI.

This is different from opencode-grok-auth (SuperGrok / api.x.ai). This plugin targets:

• grok-4.5
• grok-build
• grok-composer-2.5-fast
• any other models listed in ~/.grok/models_cache.json

What You Get

• OAuth login for provider grok-build inside opencode auth login
• Import existing ~/.grok/auth.json credentials from grok login
• Automatic token refresh through OpenCode's auth store
• Requests routed to https://cli-chat-proxy.grok.com/v1
• Required Grok CLI proxy headers injected automatically
• Model catalog loaded from ~/.grok/models_cache.json with safe defaults
• Reasoning effort variants (low / medium / high) for models that support them (e.g. Grok 4.5)

Installation

There are three supported install paths. Pick whichever fits your workflow.

1. From npm (recommended for end users)

npm install -g @ssparkluo/opencode-grok-build-auth   # or `bun add -g`

Add the plugin to your OpenCode config:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@ssparkluo/opencode-grok-build-auth"]
}

2. From a local folder via symlink (recommended for dev)

This repo ships a built-in plugin shim at plugins/grok-build-auth.ts. Symlink the project as a sub-folder into OpenCode's plugin directory and it will auto-load with no config edits:

ln -s /absolute/path/to/grok-build-auth-plugin \
      ~/.config/opencode/plugins/grok-build-auth-plugin

After restarting OpenCode the plugin is picked up from ~/.config/opencode/plugins/grok-build-auth-plugin/plugins/grok-build-auth.ts. No "plugin" entry in opencode.json is required.

3. From the repo root (inside the workspace)

Use a relative path in the project's opencode.json (relative to the config file directory):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["file://."]
}

Or drop a thin wrapper into .opencode/plugins/ — OpenCode auto-loads it with no plugin entry:

// .opencode/plugins/grok-build-auth.ts
export { default } from "../../plugins/grok-build-auth.ts";

Absolute paths in opencode.json work too, but are rarely needed inside the repo.

Authentication

Run:

opencode auth login

Choose Grok Build and one of:

1. OAuth with Grok (Grok Build / Composer) — browser login with PKCE
2. Import from Grok CLI (~/.grok/auth.json) — reuse an existing grok login session

Example Provider Config

The plugin auto-injects a default provider at runtime. You can also declare it explicitly:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@ssparkluo/opencode-grok-build-auth"],
  "provider": {
    "grok-build": {
      "npm": "@ai-sdk/openai",
      "name": "Grok Build",
      "options": {
        "baseURL": "https://cli-chat-proxy.grok.com/v1"
      },
      "models": {
        "grok-4.5": {
          "name": "Grok 4.5",
          "reasoning": true,
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "auto"
          },
          "variants": {
            "high": { "reasoningEffort": "high", "reasoningSummary": "auto" },
            "medium": { "reasoningEffort": "medium", "reasoningSummary": "auto" },
            "low": { "reasoningEffort": "low", "reasoningSummary": "auto" }
          }
        },
        "grok-build": {
          "name": "Grok Build"
        },
        "grok-composer-2.5-fast": {
          "name": "Composer 2.5 Fast"
        }
      }
    }
  }
}

Disable auto-injection if you want to manage the provider block manually:

export OPENCODE_GROK_BUILD_AUTO_CONFIG=false

Usage

opencode auth login
opencode run -m grok-build/grok-4.5 -p "hello"
opencode run -m grok-build/grok-build -p "hello"
opencode run -m grok-build/grok-composer-2.5-fast -p "hello"

Reasoning effort (Grok 4.5 / Grok Build)

OpenCode does not auto-generate effort variants for most grok* model ids. This plugin injects them from ~/.grok/models_cache.json (or safe defaults):

| Variant | reasoningEffort | |---------|-------------------| | high (default) | high | | medium | medium | | low | low |

In the TUI, switch effort with the model variants UI (often /variants or the model picker). Composer models that report supports_reasoning_effort: false get no effort variants.

How It Works

The plugin mirrors the grok-pi bridge pattern:

• OAuth: xAI OIDC PKCE flow with the public Grok CLI client ID
• Proxy: https://cli-chat-proxy.grok.com/v1
• Headers:
  • Authorization: Bearer <token>
  • X-XAI-Token-Auth: xai-grok-cli
  • x-authenticateresponse: authenticate-response
  • x-grok-client-mode: interactive or headless
  • x-grok-client-identifier: grok-shell
  • x-grok-client-version: <from ~/.grok/version.json>
  • User-Agent: grok-shell/<version> (<os>; <arch>)
  • x-grok-model-override: <model-id>
  • x-grok-conv-id: <prompt_cache_key or process session id>
  • x-grok-req-id: <uuid per request>
  • x-grok-session-id: <same as conv-id>
  • x-grok-agent-id: <from ~/.grok/agent_id or process id>
  • x-grok-source: opencode-grok-build-auth
• Native X Search: x_search is added to Responses requests by default, including allowed_tools choices. Disable it with OPENCODE_GROK_BUILD_X_SEARCH=false.
• Tracking headers: client-generated like official grok-build (not server-returned). x-grok-conv-id prefers the request body's prompt_cache_key, then falls back to a process-scoped id.

Local Development

bun install
bun run build
bun test

Troubleshooting

Plugin did not load

Clear the cached plugin and restart OpenCode:

rm -rf ~/.cache/opencode/node_modules/@ssparkluo/opencode-grok-build-auth
opencode

OAuth callback does not arrive

The plugin listens on:

http://127.0.0.1:56122/callback

If the port is busy, it falls back to a random local port.

For SSH:

ssh -L 56122:127.0.0.1:56122 user@host

Already logged in with Grok CLI

Use Import from Grok CLI or run:

grok login
opencode auth login

Credits

Inspired by:

• grok-pi — Grok CLI bridge for Pi
• opencode-google-antigravity-auth — OpenCode OAuth plugin pattern
• opencode-grok-auth — xAI OAuth plugin pattern

License

MIT