claude-codex-mcp-bridge

A local MCP bridge for Claude Code and OpenAI Codex. It combines a durable SQLite mailbox with a bounded orchestration loop that can start and resume saved Codex workers.

Claude Code ──stdio MCP──┐
                         ├── local SQLite WAL store
Codex       ──stdio MCP──┘

The default mode has no account, cloud relay, HTTP server or listening network port.

Why

Plain MCP tools are request-response. Writing a message to a mailbox does not automatically start a new model turn in another GUI chat.

This project supports two practical patterns:

1. Two visible chats: both agents use bridge_wait before going idle. A pending MCP call returns when the matching message arrives.

2. Claude coordinates Codex: Claude calls bridge_orchestrate_codex; the bridge starts a saved Codex CLI session, waits for structured output and can resume that exact session after a Fable decision.

See INSTRUCTIONS.md for copy-paste prompts.

Related MCP server: subcodex-mcp

Features

• Local SQLite WAL mailbox

• Direct messages and broadcasts

• Stable thread IDs

• Recipient-scoped acknowledgements

• Idempotency keys

• Blocking waits with sender/thread filters

• Durable Codex run state and audit events

• Saved Codex session continuation

• Optional isolated Git worktrees

• Structured worker output

• Round and timeout limits

• Explicit safety boundaries

Tools

Requirements

• Node.js 22.5 or newer

• Claude Code

• OpenAI Codex CLI

• Git, if using worktree isolation

The mailbox works anywhere Node and both MCP clients run. The automated Codex launcher uses CODEX_BIN when set, then the bundled Codex binary inside the macOS ChatGPT app when available, then codex from PATH.

Core tests run on macOS, Linux and Windows in GitHub Actions. The live Claude Desktop/Fable plus Codex Desktop workflow was developed and verified on macOS.

Install

git clone https://github.com/WebisityStudio/claude-codex-mcp-bridge.git
cd claude-codex-mcp-bridge
npm ci
npm run check

Build output is written to dist/:

npm run build

Use the absolute path to dist/server.js in both clients.

Claude Code

claude mcp add --scope user claude-codex-bridge -- node /absolute/path/to/claude-codex-mcp-bridge/dist/server.js

Codex

codex mcp add claude-codex-bridge -- node /absolute/path/to/claude-codex-mcp-bridge/dist/server.js

Restart or open a fresh session in each client after changing MCP configuration.

Windows

Use a quoted Windows path:

claude mcp add --scope user claude-codex-bridge -- node "C:\path\to\claude-codex-mcp-bridge\dist\server.js"
codex mcp add claude-codex-bridge -- node "C:\path\to\claude-codex-mcp-bridge\dist\server.js"

If Codex is not available as codex on PATH, set CODEX_BIN in the MCP server environment to the full executable path.

Quick start: two visible chats

Pick one canonical thread ID, for example invoice-review-001. Register unique names, send with bridge_send, and wait with:

{
  "agent": "claude-main",
  "fromAgent": "codex-main",
  "threadId": "invoice-review-001",
  "timeoutSeconds": 285,
  "acknowledge": true
}

Most MCP hosts cut tool calls near five minutes. The bridge caps waits at 290 seconds and defaults to 285. Agents should renew a timed-out wait while the task remains active.

A filtered wait only wakes for the exact sender and thread. Agree the thread ID before either side starts waiting.

Quick start: autonomous Codex worker

Claude calls:

{
  "coordinatorAgent": "claude-main",
  "projectPath": "/absolute/path/to/repository",
  "task": "Implement and test the bounded change",
  "threadId": "feature-x",
  "useWorktree": true,
  "maxRounds": 6
}

If the result is waiting_for_fable, Claude answers the returned question and calls bridge_continue_codex using the same run ID. The bridge resumes the exact Codex session and worktree.

The bridge does not commit, push, merge, deploy or clean worktrees automatically.

Storage

The default database is:

~/.local/share/claude-codex-bridge/bridge.sqlite

Override it in both MCP configurations with:

BRIDGE_DB_PATH=/absolute/path/to/bridge.sqlite

All MCP processes must point to the same database.

Honest limitations

• MCP cannot cold-wake a GUI chat after its model turn has ended. bridge_wait works by keeping the current call alive.

• Agent registration does not prove active processing.

• A mismatched thread filter can leave valid messages unread.

• Codex session persistence does not guarantee immediate appearance in every desktop app version's thread list.

• The default transport is local to one machine. It is not a cross-machine broker.

Safety

• No credentials are stored by this project.

• Child processes receive a small allowlist of environment variables, not the full parent environment.

• Messages are local but are stored unencrypted in SQLite.

• Do not send secrets through the mailbox unless every connected client is trusted.

• Worker prompts prohibit commits, pushes, deployments, external sends, credential changes, deletion and production mutations unless separately approved.

Development

npm test
npm run build
npm run check
npm audit --omit=dev --audit-level=high

The test suite covers mailbox routing, acknowledgements, idempotency, independent MCP processes, blocking waits, durable orchestration state, session continuation, loop limits and platform-safe process environments.

Related work

This is not the only Claude/Codex bridge. See docs/ALTERNATIVES.md for a comparison with Claude Channels bridges, ACP delegation tools and general agent mailboxes.

License

MIT