Grok × Codex Bridge

<p align="center"> <img src="./public/og.png" width="100%" alt="Grok Codex Bridge — two agents, one sharper answer" /> </p>

<h1 align="center">Grok × Codex Bridge</h1>

<p align="center"> <strong>One local bridge. Two independent agent perspectives.</strong><br /> Use your authenticated Grok Build CLI as a safe, read-only second-opinion tool inside OpenAI Codex. </p>

<p align="center"> <a href="./README.md"><b>English</b></a> · <a href="./README.zh-CN.md"><b>简体中文</b></a> · <a href="https://grok-codex-bridge.xyropy.chatgpt.site"><b>Interactive Demo</b></a> · <a href="./docs/ARCHITECTURE.md"><b>Architecture</b></a> · <a href="./docs/SECURITY.md"><b>Security</b></a> </p>

<p align="center"> <a href="https://github.com/wangsiyi7/grok-codex-bridge/stargazers"><img src="https://img.shields.io/github/stars/wangsiyi7/grok-codex-bridge?style=flat-square&color=A2FF59&labelColor=10131D" alt="GitHub stars" /></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-A2FF59?style=flat-square&labelColor=10131D" alt="MIT license" /></a> <img src="https://img.shields.io/badge/Windows-PowerShell-52E8FF?style=flat-square&labelColor=10131D" alt="Windows" /> <img src="https://img.shields.io/badge/macOS-bash-8A72FF?style=flat-square&labelColor=10131D" alt="macOS" /> <img src="https://img.shields.io/badge/protocol-MCP-F3F5F7?style=flat-square&labelColor=10131D" alt="MCP" /> </p>

[!NOTE] Unofficial community project. It is not affiliated with, endorsed by, or sponsored by xAI or OpenAI.

What this project does

Codex remains the primary coding agent. The bridge gives it four explicit MCP tools that invoke your locally authenticated Grok Build CLI in headless, advisory-only mode. Grok returns text; Codex verifies the result and owns the final answer.

Your task in Codex
       │
       ▼
Grok second-opinion skill
       │ explicit, bounded context
       ▼
Local MCP bridge ─────► Official Grok Build login
       │                       │
       └──── advisory text ◄───┘
       │
       ▼
Codex verifies, reconciles, and delivers

<table> <tr> <td width="50%" valign="top"> <h3>Independent perspective</h3> <p>Ask a second model to challenge an architecture, plan, review, or draft answer before Codex commits to a recommendation.</p> </td> <td width="50%" valign="top"> <h3>Local trust boundary</h3> <p>No hosted relay and no copied API key. Grok Build owns its official browser login and refresh lifecycle.</p> </td> </tr> <tr> <td width="50%" valign="top"> <h3>Read-only by design</h3> <p>No automatic approvals, repository mutation, background file access, Grok memory, or hidden subagents.</p> </td> <td width="50%" valign="top"> <h3>Cross-platform setup</h3> <p>One-command installers for Windows PowerShell and macOS bash, plus a self-contained Codex plugin marketplace.</p> </td> </tr> </table>

Start in one command

<details open> <summary><b>Windows PowerShell</b></summary>

irm https://raw.githubusercontent.com/wangsiyi7/grok-codex-bridge/main/install.ps1 | iex

</details>

<details> <summary><b>macOS</b></summary>

curl -fsSL https://raw.githubusercontent.com/wangsiyi7/grok-codex-bridge/main/install.sh | bash

</details>

The installer checks Codex, installs Grok Build through xAI's official installer when needed, starts the official browser login, registers the plugin marketplace, and runs a local doctor check.

Interactive demo

The companion experience is a full product walkthrough, not a static documentation page. It includes:

• bilingual English / 简体中文 switching;
• an editorial, scroll-driven explanation of the Codex → local MCP → Grok Build flow;
• an interactive browser-style demo that simulates a complete advisory handoff;
• floating depth, a focused security boundary, and responsive typography;
• platform-aware quickstart commands and copy feedback;
• complete documentation, roadmap, FAQ, and contributor entry points.

Open the interactive demo →

MCP tools

Tool	Best for	Input boundary	Output
ask_grok	Focused second opinions	Question + optional context	Concise advisory response
plan_with_grok	Independent implementation planning	Objective + constraints	Assumptions, risks, sequence, validation
review_with_grok	Diff, snippet, or document review	Supplied material only	Findings prioritized by severity
compare_with_grok	Cross-model answer critique	Question + Codex draft	Agreements, disagreements, synthesis

Try these prompts in a new Codex task:

Ask Grok for a second opinion on this architecture.
Have Grok review this diff for hidden security regressions.
Compare your answer with Grok and synthesize the strongest result.

Architecture

flowchart LR
  U["User task"] --> C["Codex"]
  C --> S["grok-second-opinion skill"]
  S --> M["Local MCP server"]
  M --> G["Authenticated Grok Build CLI"]
  G --> A["Advisory text"]
  A --> V["Codex verification + synthesis"]
  V --> U

  classDef primary fill:#10131d,stroke:#52e8ff,color:#f3f5f7
  classDef bridge fill:#10131d,stroke:#a2ff59,color:#f3f5f7
  classDef second fill:#10131d,stroke:#8a72ff,color:#f3f5f7
  class C,V primary
  class S,M bridge
  class G,A second

The adapter uses Grok Build's documented headless JSON mode rather than pretending ACP and MCP are the same protocol. See the full architecture notes.

Safety contract

The bridge does	The bridge deliberately does not
Pass explicit text selected by Codex	Read the contents of ~/.grok/auth.json
Separate Grok stdout from diagnostics	Export passwords, browser cookies, or tokens
Cap input, output, and runtime	Pass --always-approve to Grok
Return advisory text to Codex	Edit files or run repository commands through Grok
Tell the user when Grok is consulted	Treat Grok output as unquestioned authority

Read the complete security and privacy model.

Project map

grok-codex-bridge/
├── plugins/grok-codex-bridge/
│   ├── .codex-plugin/plugin.json     # Codex plugin manifest
│   ├── .mcp.json                     # Local MCP registration
│   ├── scripts/mcp-server.mjs        # Dependency-free bridge
│   └── skills/grok-second-opinion/   # Codex routing workflow
├── app/                              # Interactive bilingual demo
├── docs/                             # Architecture, security, install guides
├── install.ps1                       # Windows one-command installer
├── install.sh                        # macOS one-command installer
└── tests/                            # MCP and rendered-page regression tests

Verification

npm ci
npm run lint
npm run test:bridge
npm test

Validated locally on Windows with:

• a real Premium+ Grok Build browser login;
• a direct Grok headless response (GROK_BRIDGE_OK);
• a complete MCP request/response (MCP_GROK_OK);
• a clean public-repository installer replay;
• plugin manifest, protocol, lint, production build, and server-render tests.

Documentation by goal

Goal	Document
Install, verify, troubleshoot, uninstall	Installation guide
Understand the process and protocol boundary	Architecture
Review data flow, credentials, and guardrails	Security
Contribute safely	Contributing guide
Read in Chinese	简体中文说明

Roadmap

• [x] Official Grok Build login reuse
• [x] Four read-only MCP advisory tools
• [x] Windows and macOS one-command installers
• [x] Personal and repository Codex marketplace support
• [x] Bilingual interactive product demo
• [ ] Signed release artifacts
• [ ] Public compatibility matrix across Codex releases
• [ ] Opt-in structured citations for advisory responses
• [ ] Community-maintained prompt recipes

Contributing

Security-preserving improvements are welcome. Start with CONTRIBUTING.md, open an issue for trust-boundary changes, and keep prompt or credential logging out of pull requests and bug reports.

Acknowledgements

This project is inspired by the extensibility models documented by xAI Grok Build and OpenAI Codex. Product and company names belong to their respective owners.

License

MIT © 2026 wangsiyi7