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

One command

Run directly from the public GitHub repository:

npx --yes --package=github:WebisityStudio/claude-codex-mcp-bridge claude-codex-mcp-bridge setup

The setup command:

• builds the package automatically;

• detects and registers Claude Code and Codex;

• resolves the server's absolute path internally;

• installs the ask-codex, review-with-codex and coordinator skills;

• installs a Claude codex-teammate agent definition;

• points both clients at the same local database.

Open fresh Claude and Codex sessions after setup, then verify the bridge:

npx --yes --package=github:WebisityStudio/claude-codex-mcp-bridge claude-codex-mcp-bridge doctor
npx --yes --package=github:WebisityStudio/claude-codex-mcp-bridge claude-codex-mcp-bridge demo

Other commands:

claude-codex-mcp-bridge status
claude-codex-mcp-bridge setup --force
claude-codex-mcp-bridge uninstall
claude-codex-mcp-bridge uninstall --purge

uninstall keeps the SQLite history unless --purge is explicitly supplied.

Manual fallback

git clone https://github.com/WebisityStudio/claude-codex-mcp-bridge.git
cd claude-codex-mcp-bridge
npm ci
npm run check
node dist/cli.js setup

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

Everyday use

After opening a fresh Claude session:

/ask-codex investigate why the authentication tests are flaky
/review-with-codex focus on authentication and tenant isolation

Or simply ask Claude:

Ask Codex to implement this change and verify it.
Have Codex review this repository for security regressions.

The installed skills route these requests through ask_codex and review_with_codex. Users do not need to choose agent names, create mailbox threads or manage acknowledgements for ordinary one-shot work.

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