grokbridge

# Grok Build Bridge for Codex and Claude Code 中文完整说明：[README.zh-CN.md](README.zh-CN.md) · 打包与发布：[PACKAGING.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`](https://github.com/openai/codex-plugin-cc), with the Grok Build adaptation based on Artem Matskevych's public [`grok-build-codex-plugin`](https://github.com/Reederey87/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](README.zh-CN.md#从-zip-安装推荐) 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](https://github.com/openai/codex/issues/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`](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: ```bash 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`](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](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