codex-bridge

Connect Claude Code to a running OpenAI Codex CLI session.

codex-bridge is a Claude Code plugin and MCP server for agent to agent messaging. Let Claude and Codex discuss a problem and work towards a consensus.

It connects to the Codex session you already have open, with that session's existing context. You don't need to be a meat proxy copying prompts and answers between terminals.

Claude Code → MCP server → codex queue → your running Codex session
Claude Code ← MCP reply  ← transcript ← Codex's answer

Why I use it

I mostly use this to get Claude and Codex to "sort it out" and reach a consensus. If they disagree about an approach, they can discuss the specific points with each other instead of waiting for me to pass every message along.

That could mean settling on an implementation plan or working through a bug. It also works for code review: Codex can inspect Claude's changes, and Claude can respond to the objections.

Each agent keeps its own conversation history. Claude includes the context Codex needs with each question, and Codex's side of the exchange stays visible in its terminal.

Related MCP server: claude-agent-bridge

Requirements

This is an early release. Other Codex versions haven't been checked, and its internal session format can change between releases. Run codex queue --help to check that your CLI has the required command.

Install in Claude Code

Run these commands inside Claude Code:

/plugin marketplace add w4sspr/codex-bridge
/plugin install codex-bridge@codex-bridge
/reload-plugins

Claude Code copies the plugin into its cache and installs the locked dependencies with Bun. Restart Claude Code if the MCP server doesn't appear. See Claude Code's dependency-install behavior for details.

The bridge uses your existing Codex authentication. It needs no extra API key, and messages count towards the target session's normal model usage.

Start a conversation

1. Open Codex

In another terminal, start Codex in the project you want to discuss:

codex

Send at least one message there. The bridge can only find the session after Codex saves its first message.

2. Find the session

Back in Claude Code, ask:

Use codex-bridge to list my running Codex sessions.

Pick a session from the list. You can use its full UUID, a unique UUID prefix, or its exact name. Or just let Claude figure it out tbh. If more than one session fits, it'll probably ask.

3. Ask Codex something

Replace a1b2c3d4 with your session's UUID prefix:

/codex-bridge:talk a1b2c3d4 Review the current changes for unsafe retries and duplicate writes.

Claude sends its position and question to Codex, reads the reply, and follows up on disagreements. When the discussion ends, Claude reports what they agreed on and what remains unresolved.

The default is four rounds, with one Claude message and one Codex reply per round. Ask for a different limit in your request, such as "use up to eight rounds." The command stops earlier if the agents agree or start repeating themselves without making progress. You'll still need to judge the result, even when they agree.

This limit is part of /talk's instructions. The MCP tools themselves have no round limit.

If your session name contains spaces, use its UUID or a unique UUID prefix with /talk. Direct MCP calls accept the full name.

Use the MCP tools directly

You can also call the tools individually for your own multi-agent coding workflow:

Keep the request_id returned by a send. If the answer takes too long, pass that ID and the same thread to codex_wait_reply. The message may already have been delivered, so resending it could start the same work twice.

The MCP tool reference has the arguments, defaults, response fields, and recovery examples.

Privacy and permissions

The bridge runs locally over stdio. It has no network listener or added telemetry. It reads Codex's registry and transcript files and sends messages through codex queue.

The MCP client can read sessions across projects in the selected Codex home. That includes session titles, paths, and conversation text. Only enable it in a client you trust with that information. The bridge doesn't redact messages or transcripts.

Codex can contact its model provider and run tools in response to a queued prompt, using the target session's existing permissions. Check what you're asking the agents to share or do.

Both the bridge and Codex must use the same CODEX_HOME, which defaults to ~/.codex. Remote Codex app-server sessions aren't supported.

Troubleshooting

If no sessions appear, send a first message in Codex and check that both processes use the same CODEX_HOME. For a session that appears stopped, check its Codex terminal is still open and lsof is available. The liveness check is a heuristic, so a session listed as running isn't guaranteed to answer.

Codex may be finishing another turn when you send a message. Recover a slow reply with its request_id. Your MCP client's timeout is separate from the bridge's wait timeout.

See troubleshooting and updates for dependency problems, format errors, timeout settings, and migration from the old local marketplace.

Development

Tests use synthetic registries and transcripts; they don't need model credentials. On macOS, install coreutils and trash with Homebrew if timeout or trash is missing.

git clone https://github.com/w4sspr/codex-bridge.git
cd codex-bridge
bun install --frozen-lockfile --ignore-scripts
bun run typecheck
timeout 120 bun test
timeout 20 bun run verify:mcp
claude plugin validate .
claude plugin validate .claude-plugin/plugin.json

To load your checkout directly:

claude --plugin-dir "$PWD"

See CONTRIBUTING.md, architecture, and SECURITY.md.

License

MIT. An independent community project, unaffiliated with OpenAI or Anthropic (but I'm open to offers).