Grok Build Bridge

CI License Node.js

A Codex CLI plugin that lets you delegate reviews and bounded coding tasks from an OpenAI Codex session to the local, subscription-authenticated Grok Build CLI (xAI). It ships a bundled stdio MCP server that wraps the local grok binary, plus a skill that tells Codex when to reach for it. Grok is an explicit second-opinion / review / task channel — not a model swap for Codex's own work.

Codex session → grok-build-delegate skill routes → MCP tools → local `grok` CLI → results back under Codex approvals

Requirements

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

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

• The OpenAI Codex CLI with plugin support.

Install (local dev)

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

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.

Tools

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

Tool	Purpose
grok_build_setup	Check CLI/model discovery, authentication, bounded probes, optional single/all-model smoke readiness, fallback, and state storage.
grok_build_prompt	Run a foreground, strictly read-only Grok prompt in a workspace.
grok_build_review	Preview disclosure or send path-filtered, content-redacted Git context to xAI through the local CLI for a read-only review.
grok_build_task	Run or queue a bounded Grok task, optionally with gated workspace writes.
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.

grok_build_review sends repository context to the external xAI service. Use preview_only: true to inspect the path-filtered file list, byte count, redaction count, and coverage metadata without running inference. Execution requires external_disclosure_acknowledged: true. Sensitive path names are withheld and high-confidence credentials in included text are redacted on a best-effort basis; read-only Grok invocations expose only the built-in Read, Grep, and Glob tools, use Grok's strict sandbox, and do not expose Bash. Pass model to select the review model and timeout_ms (maximum one hour) to bound the review. Diff reviews run from a private sanitized snapshot rather than the original checkout. Review inputs and non-resumable Grok sessions are deleted immediately after the call; seven-day pruning remains as crash recovery.

Setup performs model discovery without inference by default. Set run_smoke_test: true to test the selected/default model, or pass smoke_models: "all" (or up to eight explicit model names) for per-model model_results. check_model selects the readiness target but does not itself run inference.

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. Overrides the private per-user state directory.
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.
GROK_BUILD_ALLOW_ALWAYS_APPROVE	true to permit explicitly requested unattended writes. 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_TRUST_CUSTOM_XAI_BASE_URL	true to permit sending the fallback bearer token to a non-xAI HTTPS host. Loopback HTTP remains available for local tests.
GROK_BUILD_XAI_TIMEOUT_MS	xAI API request timeout in ms. Defaults to 120000.
GROK_BUILD_NODE	Absolute path to a node binary for the bundled launcher to use, bypassing its own PATH search.

Codex's own 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 — it sets grok_build_review to approve and keeps the write-capable grok_build_task on prompt.

By default, state is stored under $XDG_STATE_HOME/grok-build-mcp, macOS Application Support, %LOCALAPPDATA%, or ~/.local/state/grok-build-mcp, depending on the platform. State directories use mode 0700 and prompt/result/log files use 0600 where POSIX modes apply. Jobs from the former temporary location remain readable for compatibility when no explicit data directory is configured. grok_build_status returns redacted operational metadata; use grok_build_result to retrieve a finished job's complete result and evidence. Completed job records and logs in the current state directory are retained for 30 days and pruned when a new job is prepared; status and result reads never delete state. Active jobs and legacy compatibility records are not pruned. Background workers maintain short ownership leases; stale jobs become orphaned only after every recorded process is confirmed gone. A stale lease with a live process retains its write lock and must be cancelled, avoiding both overlapping writers and signalling an already-reused dead PID.

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". Requests set store: false, and the fallback is never used for write-mode tasks — it uses your xAI API credits, so it stays an explicit, read-only opt-in. The default endpoint is https://api.x.ai/v1/responses. A custom remote HTTPS host additionally requires GROK_BUILD_TRUST_CUSTOM_XAI_BASE_URL=true; URL credentials, query strings, fragments, and non-loopback HTTP endpoints are rejected.

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.

An always_approve: true request is never implied and additionally requires GROK_BUILD_ALLOW_ALWAYS_APPROVE=true. Write execution still stays inside the curated capability set: the bridge uses dontAsk, so approved read/edit/test/build operations already run unattended without forwarding Grok's global --always-approve flag. Each write job captures git status and protected-path hashes before and after the run. Protected-path changes fail the task but are preserved for review rather than automatically reverted. Applying anything further still goes through Codex's normal edit/approval flow.

Delegated invocations disable Grok memory, subagents, and web search. Read-only calls remove Bash and expose only Read, Grep, and Glob. Write calls use the strict sandbox plus dontAsk, expose repository read/edit tools, and permit only the project's test/build commands and narrow read-only Git metadata commands. Sensitive-path and shell-reader denies remain in force. Local Grok instructions, configuration, and hooks still belong to the caller's trusted local environment.

Model IDs are never silently aliased. Explicit or environment-selected local models must appear in grok models; when no model is selected, the CLI-reported default is used.

Cancellation first moves a job to cancelling, terminates the recorded Grok and worker process trees, waits for confirmed exit, and only then records cancelled and releases a write lock. A failed termination remains retryable and keeps the lock rather than allowing another writer to overlap a live process.

See USAGE.md for concise criteria on what to delegate to Grok versus keep in Codex.

Community and security

• Contributing
• Support
• Security policy
• Code of Conduct
• Apache 2.0 license

The project is currently pre-1.0. Public interfaces and configuration may still evolve, with changes documented in CHANGELOG.md.

Try it

Once the plugin is enabled, ask Codex:

• "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."

Development

npm test            # node --test over tests/*.test.mjs
npm run build       # tsc type-check (JSDoc types, no emit)

Drive the tools without Codex 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