Grok Bridge

Grok Bridge is a local Model Context Protocol (MCP) server and Codex plugin that lets ChatGPT Desktop and Codex delegate substantial work to the locally installed Grok Build agent.

It supports read-only consultations, background builder/tester jobs, cancellation, session discovery, and transcript export. Delegated jobs use xhigh reasoning effort by default.

Community project. This repository is not affiliated with, endorsed by, or maintained by xAI or OpenAI. Grok and Grok Build are not included.

What it provides

Tool	Purpose
grok_doctor	Check the Grok executable, authentication, runtime, and defaults.
grok_consult	Run a synchronous, read-only consultation or review.
grok_start	Start a background builder, tester, reviewer, or research job.
grok_poll	Poll a background job and read bounded log tails.
grok_cancel	Cancel a known job and its child process tree.
grok_list	List recent bridge jobs and Grok sessions.
grok_export_session	Export a Grok session transcript as Markdown.

The bundled skill teaches Codex when to use each tool and requires independent verification of Grok's output.

Requirements

• Node.js 20 or newer.
• Grok Build installed locally.
• Grok authenticated through its own CLI, for example with grok login --oauth, or with an authentication method supported by your Grok installation.
• ChatGPT Desktop, Codex CLI, or another MCP client with STDIO server support.

By default the bridge looks for Grok at ~/.grok/bin/grok (grok.exe on Windows), then falls back to grok on PATH. Set GROK_BRIDGE_GROK_EXE to override this.

Install

Clone the repository and install the locked dependencies:

git clone https://github.com/conrad85/grok-bridge.git
cd grok-bridge
npm ci
npm run test:doctor

Option A: install as a local Codex plugin

From the cloned repository, register its local marketplace:

codex plugin marketplace add .

Restart ChatGPT Desktop, open the Plugins Directory, select the Grok Bridge marketplace, and install the plugin. The plugin bundles both the MCP server configuration and the reusable skill. See the official OpenAI plugin packaging documentation for current marketplace behavior.

Option B: configure the MCP server directly

Use the absolute path to your clone:

codex mcp add grok_bridge -- node /absolute/path/to/grok-bridge/server/index.mjs

To make the workflow skill available to new local sessions, copy skills/grok-bridge into your personal skills directory:

macOS/Linux:

mkdir -p ~/.agents/skills
cp -R skills/grok-bridge ~/.agents/skills/grok-bridge

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills" | Out-Null
Copy-Item -Recurse -Force "skills\grok-bridge" "$env:USERPROFILE\.agents\skills\grok-bridge"

Restart the desktop app after changing MCP or skill configuration.

Example requests

• "Ask Grok to review this implementation at xhigh effort."
• "Use Grok as a builder, implement the feature, and run the tests."
• "Have Grok reproduce this bug as a tester, then independently verify the result."

Configuration

Environment variable	Meaning
GROK_BRIDGE_GROK_EXE	Absolute path or command name for the Grok executable.
GROK_BRIDGE_HOME	Directory for bridge jobs and bounded logs. Defaults to ~/.grok/bridge.
XAI_API_KEY	Optional authentication method when supported by the local Grok CLI.

Safety and privacy

Builder jobs run Grok in its workspace sandbox and add explicit denials for commits, pushes, publishing, deployment, and broad destructive commands. Read-only consultations use stricter permissions. These are defense-in-depth controls, not a substitute for reviewing delegated work.

The bridge itself has no telemetry and does not bundle credentials. Grok Build may send prompts and project context to xAI as part of its normal operation. Job requests, output, and logs are stored locally under GROK_BRIDGE_HOME. Read PRIVACY.md and SECURITY.md before use.

Development

npm ci
npm run check
npm test
npm run audit:public

Tests that invoke a real authenticated Grok installation are intentionally separate:

npm run test:doctor
npm run test:live -- /absolute/project/path
npm run test:background -- /absolute/project/path
npm run test:builder -- /absolute/fixture/path

License

MIT. See LICENSE.