Grok × Codex Bridge

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

Related MCP server: codex-chatgpt-bridge

Start in one command

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

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

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

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

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

Roadmap

• Official Grok Build login reuse

• Four read-only MCP advisory tools

• Windows and macOS one-command installers

• Personal and repository Codex marketplace support

• 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