Grok Build Bridge for Codex and Claude Code

中文完整说明：README.zh-CN.md · 打包与发布：PACKAGING.zh-CN.md

Grok Build Bridge connects OpenAI Codex and Anthropic Claude Code to the local, subscription-authenticated Grok Build CLI (xAI). It delegates reviews, bounded coding tasks, current web/X research, Grok 4.5 media generation, and xAI TTS through a bundled stdio MCP server and shared routing skill. Codex or Claude Code remains the primary agent responsible for planning, approvals, diff review, verification, and final acceptance; Grok is a controlled second-opinion and implementation channel, not a model swap.

Codex / Claude Code → grok-build-delegate skill → MCP tools → local `grok` CLI / xAI TTS → host review and approval

Project origin

This repository is a locally extended derivative rather than a from-scratch implementation. Its plugin/runtime foundations come from OpenAI's Apache-2.0-licensed codex-plugin-cc, with the Grok Build adaptation based on Artem Matskevych's public grok-build-codex-plugin. This version was then adapted for the author's local Codex and Claude Code workflow, including Grok 4.5 image/video generation, subscription-authenticated TTS, Chinese documentation, packaging, tests, and additional installation and safety work. See the Git history for changes made in this repository.

Requirements

• Node.js >= 18.18
• The Grok Build CLI, installed and logged in:

  curl -fsSL https://x.ai/cli/install.sh | bash
  grok login
  

• At least one supported host: OpenAI Codex CLI with plugin support, or Anthropic Claude Code.

Install for Codex

npm install
codex plugin marketplace add /path/to/grok-build-codex-plugin
codex plugin add grok-build@grok-build-dev
node scripts/install-codex-config.mjs

For a release ZIP, extract it first and run npm ci in the extracted directory before the marketplace commands. Release archives intentionally exclude node_modules; see the Chinese installation guide for an end-to-end walkthrough.

The repository root doubles as the marketplace (.agents/plugins/marketplace.json). Run npm install before adding it — the MCP server needs @modelcontextprotocol/sdk at runtime and the plugin is cached with its node_modules. codex plugin add is still needed to register the grok-build-delegate skill.

The last step, node scripts/install-codex-config.mjs, installs the MCP server itself. On codex-cli 0.144.1, ${PLUGIN_ROOT} in .mcp.json does not resolve when Codex's session cwd is outside this checkout (openai/codex#22842), so relying on .mcp.json alone leaves the server unreachable from other repos. The installer writes an absolute-path [mcp_servers.grok-build] entry to ~/.codex/config.toml (or $CODEX_HOME/config.toml) instead — reliable regardless of session cwd. .mcp.json stays in the repo for when upstream fixes resolution. Run node scripts/install-codex-config.mjs --remove to uninstall; see dev/README.md for the full flag reference.

Codex sometimes launches plugin MCP servers with a minimal PATH (e.g. GUI/launchd contexts), where a bare node command isn't found. The installed config runs the server through a bundled launcher (mcp-server/bin/grok-build-mcp) that locates node in common install locations on its own; set GROK_BUILD_NODE=/path/to/node to force a specific binary.

Install for Claude Code

Claude Code uses the same MCP server and shared delegation skill, but it does not use the Codex plugin marketplace. From a long-lived checkout of this repository:

npm install
claude mcp add --scope user grok-build -- /bin/sh "$PWD/mcp-server/bin/grok-build-mcp"
mkdir -p "$HOME/.claude/skills/grok-build-delegate"
cp skills/grok-build-delegate/SKILL.md "$HOME/.claude/skills/grok-build-delegate/SKILL.md"
claude mcp get grok-build

Start a new Claude Code session after installing the skill. The safe default keeps repository writes disabled; enable them only by registering the MCP server with -e GROK_BUILD_ALLOW_WRITE=true, while each write call must still set write: true.

The root .mcp.json is retained for Codex plugin packaging and uses Codex's ${PLUGIN_ROOT} placeholder. For Claude Code, the supported setup is the absolute-path user-scope registration above; do not enable the repository's conflicting project-scope grok-build entry. Claude Code support is currently MCP + skill integration, not a one-click .claude-plugin package.

Tools

The MCP server exposes ten tools. Each takes a cwd (the target repository's absolute path).

Tool	Purpose
grok_build_setup	Check the local Grok CLI, authentication, model, fallback, and state storage.
grok_build_prompt	Run a foreground, strictly read-only Grok prompt in a workspace.
grok_build_review	Collect safe Git context and run a read-only Grok code review.
grok_build_task	Run or queue a bounded Grok task, optionally with gated workspace writes.
grok_build_image	Generate an image or edit local reference images with Grok 4.5.
grok_build_video	Generate a 6- or 10-second video with Grok 4.5 from a source image or generated first frame.
grok_build_tts	Generate an MP3 through xAI TTS using the existing local Grok Build OIDC subscription login.
grok_build_status	List active or all stored jobs for a repository, with process liveness.
grok_build_result	Return the stored result and evidence for a finished job.
grok_build_cancel	Cancel an active job, terminate its process tree, and release its write lock.

grok_build_task runs in the foreground by default; pass background: true for long runs, then poll grok_build_status and read grok_build_result when the job finishes.

Configuration

Environment variables read by the MCP server:

Variable	Purpose
GROK_BUILD_DEFAULT_MODEL	Default Grok model passed to the CLI. Unset uses Grok's own default.
GROK_BUILD_PLUGIN_DATA	Directory for job state and review inputs. Defaults to a temp dir.
GROK_BUILD_API_FALLBACK	true to permit the read-only xAI API fallback globally. Defaults to false.
GROK_BUILD_ALLOW_WRITE	true to allow write-mode tasks. Defaults to off.
XAI_API_KEY	xAI API key. Required for the API fallback.
GROK_BUILD_XAI_BASE_URL	xAI API base URL. Defaults to https://api.x.ai/v1.
GROK_BUILD_XAI_TIMEOUT_MS	xAI API request timeout in ms. Defaults to 120000.
GROK_BUILD_GROK_AUTH_PATH	Override the Grok Build OIDC store used only by TTS. Defaults to ~/.grok/auth.json.
GROK_BUILD_TTS_BASE_URL	Override the TTS API base URL. Defaults to https://api.x.ai/v1.
GROK_BUILD_NODE	Absolute path to a node binary for the bundled launcher to use, bypassing its own PATH search.

The host agent's sandbox and approval policy governs applying any patch Grok proposes. A per-tool approval snippet for ~/.codex/config.toml lives in dev/config-snippet.toml. The installer applies the same policy: read-only setup, prompt, review, status, and result tools are approved automatically, while the write-capable grok_build_task, process-stopping grok_build_cancel, and quota-consuming grok_build_image / grok_build_video / grok_build_tts calls stay on prompt. This automatic policy installation is Codex-specific; Claude Code follows its own MCP permission settings.

Media generation

Media calls always use the local grok-4.5 model and never use the xAI API fallback. They parse Grok's completed media events and return the verified absolute file path in artifact.path.

• grok_build_image: text-to-image, or reference-based editing when reference_images contains one to seven absolute local paths. Named real people require a genuine reference image.
• grok_build_video: animate an absolute source_image, or omit it to let Grok create a first frame and then animate it. Duration is 6 or 10 seconds; resolution is 480p or 720p.

Generated files live in Grok's local session directory. Both tools require manual MCP approval because they create media and may consume subscription quota.

TTS generation

grok_build_tts calls xAI's dedicated /v1/tts endpoint with the OIDC access token already stored by Grok Build in ~/.grok/auth.json. It does not read or use XAI_API_KEY, and it never returns the token. The default is voice eve, language en, and MP3 output; pass the matching ISO language code for other languages (for example zh). Built-in voice IDs include ara, leo, rex, and sal, and custom voice IDs are accepted. An explicit output_path must be an absolute .mp3 path inside cwd; without one, the tool creates a unique file under cwd/grok-build-output/.

The bridge asks the Grok CLI to refresh an expiring login, and retries once after HTTP 401. TTS stays on manual MCP approval because it writes a file and may consume subscription quota.

Reference input gotchas: resize large inputs to a longest edge of 1280 px before calling the tool (sips -Z 1280 on macOS). The server rejects references over 5 MiB or 2048 px on either edge before invoking Grok. A single-image edit preserves the source aspect ratio; to change it, first generate a base image at the target ratio and then edit with both the identity reference and base.

Grok Build Agent search remains available through read-only grok_build_task. Current web/X research should run with background: true and timeout_ms: 180000 or longer, followed by grok_build_status and grok_build_result. Ask Grok to use web_search / web_fetch, return direct URLs, and separate official or first-party posts from community sources. ACP carries those Agent tool events, but availability still depends on the local Grok model, flags, and permission configuration.

If a search is incomplete, cancelled, or timed out, resume result.session_id when available and retry at most once. When the user explicitly requested Grok, the skill must report a second failure and ask permission before switching to the host's web search; it may use host web access only to verify that Grok-returned URLs resolve.

API fallback

By default all work runs through your local grok CLI. The read-only xAI API fallback fires only when all of these hold:

• it is explicitly allowed — allow_api_fallback: true on the call, or GROK_BUILD_API_FALLBACK=true;
• XAI_API_KEY is set;
• the local grok CLI is missing or unauthenticated; and
• the request is read-only.

Fallback results are marked source: "xai_api_fallback". The fallback is never used for write-mode tasks — it uses your xAI API credits, so it stays an explicit, read-only opt-in.

Write mode

Write mode is gated in v1 and off by default. Both gates must be satisfied:

1. the server environment has GROK_BUILD_ALLOW_WRITE=true, and
2. the call sets write: true on grok_build_task.

--always-approve is never implied; always_approve only takes effect for a write task and only when explicitly requested. Each write job captures git status before and after the run as evidence, so you can see exactly what changed. Applying anything further still goes through the host agent's normal edit/approval flow.

See USAGE.md for concise criteria on what to delegate to Grok versus keep in the host agent.

Try it

Once the bridge is enabled, ask Codex or Claude Code:

• "Use Grok Build to run its setup diagnostics for this repo."
• "Use Grok Build to explain what this repository does (read-only)."
• "Use Grok Build to review my working tree."
• "Ask Grok Build for an adversarial review of this branch against main."
• "Use Grok 4.5 to generate a 16:9 cinematic rocket launch image."
• "Use Grok 4.5 to create a 6-second 16:9 video at 720p."
• "Use my Grok subscription to turn this Chinese script into an MP3 with voice leo."

The grok-build-delegate skill also allows selective implicit routing for well-specified, verifiable work such as reviewing a diff, investigating a focused failure, implementing an already-written plan, or making mechanical edits. The host agent keeps architecture, product judgment, diff review, test verification, and final acceptance. Write delegation remains double-gated.

Development

npm test            # node --test over tests/*.test.mjs
npm run build       # tsc type-check (JSDoc types, no emit)
npm run package:plugin # create a clean versioned ZIP and SHA-256 file

Drive the tools without Codex or Claude Code using the dev runner or the server self-test:

node mcp-server/src/dev-runner.mjs setup --cwd "$PWD"
node mcp-server/src/server.mjs --self-test

npm run bump-version / npm run check-version manage the coupled version strings.

Status

The Grok Build CLI is early beta — its flags and JSON output may change. Output parsing is kept deliberately tolerant, and job success is read from Grok's stopReason (EndTurn = clean) rather than exit codes. Expect rough edges.

License

Apache-2.0