grok-build-plugin

A ccbud sidecar plugin that runs Claude Code and Codex on Grok (xAI) by reusing your Grok subscription login — no API key, no per-token billing. ccbud forwards standard OpenAI-Responses requests to this plugin, which reuses the login, refreshes the token, and reshapes traffic so xAI accepts it.

Rewritten in Node.js (Node built-ins only, zero dependencies) and aligned with the official open-source Grok Build CLI so the reuse is faithful: the default upstream is xAI's own subscription proxy and requests carry the same auth headers the CLI sends.

Auth

• Reads ~/.grok/auth.json (written by the official Grok CLI) and uses its OAuth token as a Bearer. Sign in with the Grok CLI first — zero setup if you already use grok. The credential format is the official one (a map keyed by "<issuer>::<client_id>", access token under key).
• Refreshes the token before expiry and on any upstream 401, via OIDC discovery against https://auth.x.ai (public client + PKCE, no secret).
• If no Grok CLI login exists, login runs an interactive OAuth 2.0 + PKCE browser flow itself (loopback callback on 127.0.0.1:56121) and caches the result under <home>/auth/xai.json. It never mutates the Grok CLI's own file.

Upstream routing

Each model is sent to the endpoint that actually serves it (a reused subscription token is accepted at both):

Model	Upstream	Auth
grok-build, grok-composer-*, unknown	https://cli-chat-proxy.grok.com/v1	Bearer + X-XAI-Token-Auth: xai-grok-cli + x-grok-client-* (as the CLI sends)
grok-4.5, grok-4.3, grok-3-mini	https://api.x.ai/v1	bare Bearer

grok-build (xAI's coding model, 500k context) is supported_in_api: false — it is only reachable through the cli-chat-proxy, which is why reusing the subscription this way unlocks it. Pass --upstream URL (or CCBUD_GROK_UPSTREAM) to force every model through one endpoint instead.

Use

Install via ccbud's plugins page → 从 Git 添加 (needs git + bun): ccbud clones, runs make dist, and registers a Grok service. Or run standalone:

make build                                    # bun compiles a standalone binary
bin/cc-bud-grok-build-plugin serve --port 8899
# or, straight from source:
node src/main.mjs serve --port 8899

curl -N http://127.0.0.1:8899/v1/responses -H 'content-type: application/json' \
  -d '{"model":"grok-build","stream":true,"input":[{"role":"user","content":"hi"}]}'

Commands: serve · login · status · version. make dist cross-compiles the per-platform binaries referenced by plugin.json.

Extras

• Image generation is exposed as a default generate_image tool: when the model calls it the plugin hits xAI's image endpoint (api.x.ai/v1/images/generations, model grok-imagine-image-quality), feeds the result back, and inlines the image as a base64 data URI. Disable with CCBUD_GROK_DISABLE_IMAGE_TOOL=1.
• Stream normalization: xAI's reasoning_text.* events are rewritten to the standard Responses reasoning_summary_text.* surface; unknown events pass through.

Environment overrides

Var	Effect
GROK_HOME	Grok CLI home to read auth.json from (default ~/.grok)
CCBUD_GROK_PLUGIN_HOME	plugin state/cache dir (default ~/.ccbud/plugins/grok-build)
CCBUD_GROK_UPSTREAM	force one upstream for all models
CCBUD_GROK_API_BASE	override the api.x.ai base used for public models
CCBUD_GROK_IMAGE_BASE	override the image-generation base
GROK_CLIENT_VERSION / GROK_CLIENT_IDENTIFIER	values sent in x-grok-client-version / -identifier
CCBUD_GROK_DISABLE_IMAGE_TOOL	do not inject the generate_image tool

Caveat: refreshing a token borrowed from the Grok CLI may rotate it and log the CLI out. If that happens, just re-run grok login.

Requires Bun to build (or Node ≥18 to run from source). GPL-3.0-only.