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

```text
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>

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

</details>

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

```bash
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 →](https://grok-codex-bridge.xyropy.chatgpt.site)**

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

```text
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

```mermaid
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](./docs/ARCHITECTURE.md).

## 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](./docs/SECURITY.md).

## Project map

```text
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

```bash
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](./docs/INSTALL.md) |
| Understand the process and protocol boundary | [Architecture](./docs/ARCHITECTURE.md) |
| Review data flow, credentials, and guardrails | [Security](./docs/SECURITY.md) |
| Contribute safely | [Contributing guide](./CONTRIBUTING.md) |
| Read in Chinese | [简体中文说明](./README.zh-CN.md) |

## 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](./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](./LICENSE) © 2026 wangsiyi7