Skip to content

buidangminh23/codex-mcp-bridge

v2.3.2MIT

Connect ChatGPT to your own Codex Desktop projects and conversations.

Connect Claude, Codex, and Antigravity through MCP. Send work between native Desktop conversations or use independent CLI background workers.

Supports Windows, macOS, and Linux. Native Desktop integration supports Windows and macOS.

https://github.com/user-attachments/assets/98b23989-826f-4d7d-9dcb-ad7dd2739095

Installation

Package — npm

Requires Node.js 22.13+. Use the same command for a fresh install or an update.

Windows PowerShell

npx.cmd -y @minhspark/codex-mcp-bridge@latest

macOS / Linux / WSL

npx -y @minhspark/codex-mcp-bridge@latest

Run the command directly in an interactive terminal. It installs the package, applies Claude/Codex/Antigravity settings, and verifies the background relay. Windows installs into %APPDATA%\npm without administrator rights. Existing permissions, project grants, custom settings, and disabled services are preserved.

For native handoffs, sign in to the Desktop apps and open the same saved project in Codex Desktop and Claude Desktop's Code tab. The shared Claude chat connector is a separate local app-server route.

Setup supplies a missing Codex CLI. Install and authenticate Claude Code and agy separately for their workers; CLI authentication is separate from Desktop sign-in.

Windows setup · macOS setup · Project permissions

Independent background workers

Codex ↔ Claude, Codex ↔ Antigravity, and Claude ↔ Antigravity workers communicate through a per-user service, even while Desktop apps are closed or unresponsive. Workers use separate CLI sessions and require an authenticated provider, a running service, and an authorized project.

  • MCP tools: worker_status, list_workers, send_to_worker, read_worker_delivery.
  • Terminal: worker-relay status, worker-relay list, worker-relay send, worker-relay read.
  • Authorize a selected project with bridge-projects allow-project <absolute-project-path>.

On Windows, add .cmd to terminal commands. Provider quotas and tool permissions still apply. Worker setup and authorization

Verify the installation

codex-bridge-setup --check
worker-relay status

On Windows use codex-bridge-setup.cmd --check and worker-relay.cmd status. The first command checks saved settings; the second checks the independent service and CLI readiness.

Check native connections with the tools available inside each client:

ClientStatus tool
Claude Codecodex_bridge_status
Codexclaude_bridge_status, native_relay_status
Codex / Claude with Antigravityantigravity_bridge_status
Antigravityagent_bridge_status

Confirm a reply on each route used. Saved configuration alone does not verify live delivery.

Use

  • Claude → Codex: “Send this review to my Codex task in this project and wait for its reply.”
  • Codex → Claude: “Send this result to my Claude Desktop Code session in this project.”
  • Background work: “Send this task to a Claude worker in this project.”
  • Another computer: use remote_codex over SSH with an existing Desktop task.

Native handoffs preserve the actual sender and destination permissions. Antigravity App replies stay in their App conversation; independent workers return separate delivery receipts.

Continue unfinished work in its original conversation. If delivery times out or is uncertain, inspect the original receipt before sending again. Daily handoffs

ChatGPT plugin

Open Codex Bridge to connect ChatGPT to a selected project on Windows or macOS. After installing the package, pair the connector:

codex-sites-connector --pair --site https://codex-mcp-bridge.buidangminh23.chatgpt.site --roots "/absolute/project/path"

On Windows use codex-sites-connector.cmd and a Windows project path. Open the printed pairing URL and select Connect this computer. Keep Codex Desktop and the connector running.

The hosted service stores account/connector identifiers, prompts, and returned results; its operator, Bui Dang Minh, can access these records. Disconnecting revokes access but does not erase history or stop dispatched tasks. Request deletion through support without posting private content publicly. Availability follows OpenAI's Sites access rules.

Optional workflow skill

Install the hosted workflow's Markdown instructions with:

npx skills add buidangminh23/codex-mcp-bridge --skill codex-bridge

Use npx.cmd on Windows. The skill requires the hosted plugin and a paired connector; it does not install the local bridges.

Troubleshooting

Rerun the installation command to update, or codex-bridge-setup to repair settings. Use --dry-run to preview changes and --check --json to inspect configuration. Add .cmd on Windows.

Include the Bridge diagnostic block when reporting an issue. Retain the original request/delivery ID after a timeout and remove private data from surrounding logs.

Documentation

Optional active-install statistics

Usage reporting is off by default. Use codex-mcp-bridge telemetry status to inspect it, or telemetry enable / telemetry disable to change it. Reports include a random installation ID, UTC day, version, and OS; no chats, paths, accounts, or credentials. DO_NOT_TRACK=1 or CODEX_BRIDGE_TELEMETRY=0 disables reporting.

Analytics · Contributing · MIT license