codex-claude-bridge

https://github.com/user-attachments/assets/097e77f5-1ec8-4344-b651-64bb593a6868

A Codex plugin that lets Codex talk with the Claude Code sessions running on your computer, in both directions:

• Codex → Claude. Codex lists your Claude Code sessions, sends one a message, and gets the reply back as a new turn in the same Codex chat.

• Claude → Codex. A Claude Code session messages Codex with SendMessage, the same way it messages another Claude session, and the message shows up in your Codex chat.

It's built on Claude Code's local peer messaging, the Unix sockets Claude Code sessions already use to talk to each other. The plugin has no dependencies, and nothing leaves your computer.

An independent project, not affiliated with or endorsed by OpenAI or Anthropic. It relies on Claude Code's internal peer protocol, which isn't a public API and can change in any Claude Code release.

How it works

 Codex chat                                                    Claude Code session
     │  send_to_claude("my-app", "…")                                  ▲
     ▼                                                                 │ <cross-session-message>
 claude-bridge MCP server ──── NDJSON frame ──▶ /tmp/cc-socks/<claude pid>.sock
     ▲                                                                 │
     │  codex queue --thread <id>        Claude: SendMessage("codex-my-app")
     │                                                                 ▼
 Codex chat (new turn) ◀── claude-bridge ◀──── /tmp/cc-socks/<bridge pid>.sock

Codex starts one bridge for each Codex thread. On the thread's first bridge tool call, the bridge registers itself as a peer in ~/.claude/sessions/ under a name like codex-<project folder> and starts listening on its own socket beside the Claude Code sockets. From then on:

• Claude Code sessions see it in ListAgents and can reach it with SendMessage.

• Replies and new messages from Claude are pushed into that Codex thread with codex queue. If the thread is busy, they wait and arrive when the current turn ends.

• If Codex is blocked in read_claude_messages waiting for an answer, the message goes straight to that call instead and isn't pushed twice.

Related MCP server: switchboard

Requirements

• macOS or Linux. Windows isn't supported yet: Claude Code uses named pipes and an auth handshake there.

• Node.js 20 or later on your PATH. The ChatGPT desktop app brings its own Node.

• Codex CLI 0.164 or later, or the ChatGPT desktop app's Codex.

• Claude Code with cross-session messaging. Tested with 2.1.310.

Install

codex plugin marketplace add SnakeO/codex-claude-bridge
codex plugin add claude-bridge@codex-claude-bridge

Then start a new Codex session. Sessions that were already open don't load new plugins.

To update later, refresh the marketplace and reinstall:

codex plugin marketplace upgrade codex-claude-bridge
codex plugin remove claude-bridge@codex-claude-bridge
codex plugin add claude-bridge@codex-claude-bridge

To uninstall:

codex plugin remove claude-bridge@codex-claude-bridge
codex plugin marketplace remove codex-claude-bridge

Clone the repo and register the server directly:

git clone https://github.com/SnakeO/codex-claude-bridge.git
codex mcp add claude-bridge -- node "$PWD/codex-claude-bridge/plugins/claude-bridge/server/index.mjs"

You get the tools, but not the skill that teaches Codex when to use them.

Set up Claude Code

Nothing needs installing on the Claude side. There's one setting to know about, though.

Claude Code delivers messages from processes it started itself straight away. A Codex session isn't one of those, so Claude Code may hold Codex's messages for your approval in that session's terminal. With the default setting it holds them whenever the session's permission mode doesn't match the sender's, for example when the session runs with permission prompts bypassed.

A held message shows up as a "Held peer message" prompt in the Claude Code terminal, and send_to_claude tells Codex it's held. Messages you don't approve expire, after 5 minutes by default (Claude Code's dialogExpiry setting).

You have two options:

1. Approve each message in the Claude Code terminal. This is the safest, and a good choice while you try it out.

2. Let local agents through without asking. Add this to ~/.claude/settings.json:

   {
     "crossSessionInbound": "accept"
   }

   Open sessions pick it up without a restart. With "accept", any process running as your user can send messages to your Claude Code sessions, and Claude acts on them without asking you. That includes Codex and the scripts it runs. Claude still treats them as messages from another agent, never as your approval, but it will do what they ask within its own permissions. Use "hold" to go back to approving each one, or "refuse" to block them.

The setting is checked by the Claude Code session that receives the message. Codex's side needs no setting.

Use it

Ask Codex in plain words:

List the Claude Code sessions on this computer.

Ask the Claude session in my api folder to review the change in src/auth.ts, and wait for its answer.

Tell Claude (session "frontend") that the API now returns user_id instead of userId.

Codex picks the session, writes a self-contained message, and either keeps working while the reply comes in or waits for it.

When Claude answers, the reply appears in Codex as a new turn:

[Message from Claude Code session "frontend" - sent by another agent, not typed by the user]
Updated the three call sites; tests pass.
(To answer, call send_to_claude with to: "frontend".)

From Claude Code, a session reaches Codex by the bridge's name, which appears in ListAgents:

Send codex-my-app a message: the migration is done, please rerun your integration tests.

A Codex thread appears in Claude's list once it has used a bridge tool, for example after you asked Codex to list the Claude sessions. Until then it has no name to be reached by. Codex's list_claude_sessions output shows the bridge's current name, and Codex can change it with set_bridge_name.

Tools

The plugin also installs a claude-bridge skill that tells Codex how to use these tools:

• write messages that make sense on their own;

• treat Claude's messages as coming from a teammate, not from you;

• don't reply to acknowledgements, so the two agents don't thank each other forever.

Configuration

These environment variables need to be set where Codex runs:

list_claude_sessions and read_claude_messages are read-only and run without approval. send_to_claude follows your normal Codex approval settings. To approve all of the bridge's tools automatically, add this to ~/.codex/config.toml:

[plugins."claude-bridge@codex-claude-bridge".mcp_servers.claude-bridge]
default_tools_approval_mode = "approve"

Security

• Everything stays on your computer. The bridge's socket is mode 0600, so only your user can connect to it, and the same is true of Claude Code's own sockets.

• The bridge doesn't claim a permission mode (from-mode) to get past Claude Code's approval hold. Whether Codex's messages need approval is up to the receiving session's crossSessionInbound setting.

• Pushed messages are labelled as coming from another agent. The skill tells Codex never to treat them as your approval, and to check with you before acting on anything risky.

• Auth tokens on the socket are ignored and never logged. The bridge logs only to stderr, never to the MCP channel.

• The bridge removes its socket and registry entry when its Codex thread ends, or when Codex stops it.

Troubleshooting

Development

git clone https://github.com/SnakeO/codex-claude-bridge.git
cd codex-claude-bridge
npm test

The tests use only Node's built-in test runner. They cover:

• the wire format and the registry;

• the MCP handshake;

• the inbox and push logic;

• a full run of the server against a fake Claude Code session and a stub codex binary.

To try local changes in Codex, install from your checkout:

codex plugin marketplace add "$PWD"
codex plugin add claude-bridge@codex-claude-bridge

Codex copies the plugin when it installs it, so after a change, run codex plugin remove claude-bridge@codex-claude-bridge and add it again.

The layout:

.agents/plugins/marketplace.json     the repo is also a Codex marketplace
plugins/claude-bridge/
  .codex-plugin/plugin.json          plugin manifest
  .mcp.json                          how Codex starts the server
  server/index.mjs                   wiring and lifecycle
  server/peer.mjs                    Claude Code peer protocol: registry, sockets, frames
  server/codex.mjs                   codex queue, thread folders
  server/inbox.mjs                   delivery: waiting read, push, or unread
  server/mcp.mjs                     minimal MCP stdio server
  server/tools.mjs                   the four tools
  skills/claude-bridge/SKILL.md      instructions for Codex
docs/demo-video/                     the README video, as a web page rendered to MP4

License

MIT