codex-mcp-bridge

Send prompts and replies between Claude and Codex, keeping each conversation in its own app. Supports Windows, macOS, and Linux; native Desktop integration supports Windows and macOS.

npm install -g @minhspark/codex-mcp-bridge@latest

Requires Node.js 22+. In Windows PowerShell, use npm.cmd instead of npm. Run the same command to update; reconnect MCP servers if their settings or installation paths changed.

On macOS or Linux you can install with Homebrew instead, which brings its own Node.js:

brew install buidangminh23/tap/codex-mcp-bridge

Update with brew upgrade codex-mcp-bridge. The installers record Homebrew's stable opt paths, so registrations keep working after an upgrade and running bridges reload the new version. Keep one install channel: whichever of npm or Homebrew comes first on PATH provides the commands.

Windows · macOS · Linux / WSL · ChatGPT plugin

Install and sign in to Codex Desktop and Claude Desktop. Save the project in Codex Desktop and open the same directory in Claude Desktop's Code tab. Have the Codex and Claude Code CLIs available.

If the Codex CLI is missing, run winget install --id OpenAI.Codex --exact, open a new terminal, then run codex.exe login.

$env:CODEX_EXE = (Get-Command codex.exe).Source
codex-native-relay-install.cmd --desktop-tasks
codex-mcp-bridge-install.cmd --desktop-tasks
$env:CODEX_BRIDGE_DESKTOP_TASKS = "1"
claude-mcp-bridge-install.cmd

Next: register Claude Code, add relay pipe forwarding, then verify.

Install and sign in to Codex Desktop and Claude Desktop. Save the project in Codex Desktop and open the same directory in Claude Desktop's Code tab.

npm install -g @openai/codex@latest
codex login
codex-native-relay-install --desktop-tasks
codex-mcp-bridge-install --desktop-tasks
CODEX_BRIDGE_DESKTOP_TASKS=1 claude-mcp-bridge-install

Keep bootstrap enabled on the first relay install. Next: register Claude Code, add relay pipe forwarding, then verify.

Claude Desktop and Claude Code have separate MCP registrations. If claude --version is unavailable, install Claude Code first. For a new registration, replace the example project path below with the actual directory. Preserve custom settings if codex-bridge is already registered.

$bridgeRoot = Join-Path ((npm.cmd root -g).Trim()) '@minhspark/codex-mcp-bridge'
claude mcp add --scope user codex-bridge `
  -e "CODEX_BIN=$((Get-Command codex.exe).Source)" `
  -e CODEX_BRIDGE_DESKTOP_TASKS=1 `
  -e CODEX_BRIDGE_AUTOSTART=0 `
  -e CODEX_BRIDGE_THREAD_POLICY=roots `
  -e "CODEX_BRIDGE_ALLOWED_ROOTS=C:\Projects\YourProject" `
  -- (Get-Command node.exe).Source (Join-Path $bridgeRoot 'src/mcp-supervisor.mjs') index.mjs

bridge_root="$(npm root -g)/@minhspark/codex-mcp-bridge"
claude mcp add --scope user codex-bridge \
  -e CODEX_BIN="$(command -v codex)" \
  -e CODEX_BRIDGE_DESKTOP_TASKS=1 \
  -e CODEX_BRIDGE_AUTOSTART=0 \
  -e CODEX_BRIDGE_THREAD_POLICY=roots \
  -e CODEX_BRIDGE_ALLOWED_ROOTS="$HOME/YourProject" \
  -- "$(command -v node)" "$bridge_root/src/mcp-supervisor.mjs" index.mjs

bridge_root="$(brew --prefix)/opt/codex-mcp-bridge/libexec/lib/node_modules/@minhspark/codex-mcp-bridge"
node_bin="$(brew --prefix)/opt/node/bin/node"

Separate multiple allowed directories with ; on Windows or : on macOS/Linux.

On Windows and macOS, codex-native-relay-install adds this to the relay's entry in ~/.codex/config.toml (or $CODEX_HOME/config.toml) and keeps its other settings:

[mcp_servers.codex-native-relay]
env_vars = ["CODEX_APP_TOOLS_PIPE_PATH"]

If you register the relay by hand, add the same line and append the variable name if env_vars already exists. Only the name is saved, never the temporary pipe path. Restart Codex Desktop after active work finishes so it relaunches the relay.

Use Node.js 22+ and signed-in Codex and Claude Code CLIs under the same Linux user. This mode uses a local app-server; native Desktop integration requires Windows or macOS.

npm install -g @openai/codex@latest
codex login
CODEX_BRIDGE_DESKTOP_TASKS=0 claude-mcp-bridge-install
bridge_root="$(npm root -g)/@minhspark/codex-mcp-bridge"
claude mcp add --scope user codex-bridge \
  -e CODEX_BIN="$(command -v codex)" \
  -e CODEX_BRIDGE_DESKTOP_TASKS=0 \
  -e CODEX_BRIDGE_AUTOSTART=1 \
  -e CODEX_BRIDGE_THREAD_POLICY=roots \
  -e CODEX_BRIDGE_ALLOWED_ROOTS="$HOME/YourProject" \
  -- "$(command -v node)" "$bridge_root/src/mcp-supervisor.mjs" index.mjs

Reconnect the affected MCP servers in the actual client tasks; Claude Code provides /mcp. Run these MCP tools inside the apps:

Send a short message and confirm its reply in both directions. Registration alone does not prove delivery.

• 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.”
• Codex → Codex on another computer: configure an SSH project mapping, then use remote_codex to list, read or message an existing Desktop task. Different Codex accounts on the two computers are supported. See remote Codex setup.
• New work: “Create a new Codex conversation for this feature and send the brief there.”

Continue unfinished work with its original threadId. For an authorized new Desktop task, use delegate_to_codex or start_codex_thread with a fresh UUID requestId; retain that ID on retries. If a send times out, use wait_codex_reply with the original deliveryId before retrying the message.

Daily handoffs · Project permissions · All tools and settings

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

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

In PowerShell use codex-sites-connector.cmd and a Windows path such as C:\Projects\YourProject. Open the printed pairing URL, sign in, and select Connect this computer. Keep Codex Desktop and the connector running; use codex-sites-connector to reconnect later.

The MCP endpoint is https://codex-mcp-bridge.buidangminh23.chatgpt.site/mcp. Plugin availability follows OpenAI's Sites access rules; a public directory listing is not claimed.

• Command missing: open a new terminal and check Node.js 22+ and the global npm directory (or Homebrew's bin) on PATH.
• PowerShell blocks scripts: use npm.cmd, installer .cmd launchers, and codex.exe.
• No sessions or wrong project: open the intended Claude Code session and use the exact project directory saved in Codex Desktop.
• Relay unavailable: Codex Desktop runs the relay only while a task has its MCP servers loaded. On macOS the bridge opens the destination task (or your project's latest Codex task) in the background to start it; otherwise open a regular project task and send it a turn. If it still fails, check pipe forwarding and run native_relay_status in that task.
• Timeout or unconfirmed send: inspect the original task or receipt before sending again.

More fixes · Report an issue

Usage reporting is off by default. Manage it with codex-mcp-bridge telemetry enable, telemetry status, or telemetry disable. Reports contain a random installation ID, UTC day, version, and OS; no chat content, paths, account identity, or credentials. DO_NOT_TRACK=1 or CODEX_BRIDGE_TELEMETRY=0 disables reporting. Disabling removes the local ID; submitted records expire after 90 days during ingestion.

Analytics dashboard · Release notes · Contributing · MIT license