# 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.

Write tasks receive no shell capability by default. When a bounded implementation genuinely
needs it, pass `allow_bash: ["test"]` for focused tests/type checking or
`allow_bash: ["render"]` for a short render command. These are fixed categories, not arbitrary
shell patterns. They satisfy Grok's permission layer, but Grok's independent safety classifier
can still reject complex command shapes. The bridge therefore also injects a strict shell policy:
use native tools for file inspection, never use `cd`, command chaining, globs, Git, or process
inspection, and leave full-suite verification to the host agent. `always_approve` does not relax
that classifier and should not be used as a substitute for a bounded command shape.

One exception is worth knowing before you enable it: setting `always_approve: true` rule-allows
`Bash` wholesale for that run (the deny list still applies, so `rm`/`mv`/`cp` and Git-write
commands stay blocked, and the workspace sandbox still contains execution). This is required for
unattended/headless write jobs, because grok 0.2.106 auto-cancels the whole run the instant an
un-rule-allowed command hits its permission prompt — even under `--always-approve`. So
`always_approve` widens shell access rather than merely skipping prompts: use it only for
unattended runs you intend to review by diff afterward.

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