Codex Claude Bridge

English · Türkçe

One local MCP server that lets Codex and Claude Code coordinate through a shared task board and message inbox.

It uses the standard MCP stdio transport. No API key, web server, or cloud account is required. Both clients run the same server program and point at the same local data directory.

Scope: version 0.1.0 is for a single machine or a trusted shared filesystem. It is not a secure multi-user or internet-facing collaboration service.

What it provides

• Create, list, claim, update, block, and complete shared tasks.
• Send general messages or messages attached to a task.
• Prevent active tasks from being claimed by both agents.
• Atomically write the shared state, with a cross-process lock for concurrent client calls.

Quick start

Windows (PowerShell)

git clone https://github.com/nevzoom/codex-claude-bridge-mcp.git
cd codex-claude-bridge-mcp
npm install
npm run build
.\scripts\install.ps1

This registers the server with both locally installed CLIs and stores shared state in ~/.codex-claude-bridge. Restart Codex and Claude Code afterwards.

To register only one client:

.\scripts\install.ps1 -Codex
.\scripts\install.ps1 -Claude

macOS / Linux

git clone https://github.com/nevzoom/codex-claude-bridge-mcp.git
cd codex-claude-bridge-mcp
npm install
npm run build
bash scripts/install.sh

Use bash scripts/install.sh --codex or --claude to register only that client. To use another shared directory, pass --data-dir /path/to/bridge-data (or -DataDirectory in PowerShell).

Manual MCP configuration

The installer runs the official CLIs for you. If you prefer to configure manually, register this stdio command with both clients, using the same data directory:

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

Set this environment variable for both registrations:

CODEX_CLAUDE_BRIDGE_DATA_DIR=/absolute/path/to/shared-bridge-data

Codex also supports project/global MCP configuration in config.toml; Claude Code supports project/user MCP registration. The supplied installers use user-level registration so the bridge is available across projects.

When this variable is omitted, the server uses ~/.codex-claude-bridge. This is convenient when both clients run under the same operating-system user. Set it explicitly whenever clients run under different users or machines.

MCP tools

Tool	Purpose
create_task	Add a shared task.
list_tasks	View tasks, optionally by status.
claim_task	Mark a task as owned by Codex, Claude, or a human.
update_task	Change its status, owner, or result.
post_message	Send a general or task-linked message.
read_messages	Read messages for an agent or task.

Suggested agent workflow

1. Create a discrete task with create_task.
2. The receiving agent calls list_tasks, then claim_task before working.
3. Share important context with post_message.
4. Finish with update_task using status: "done" and a concise result; use blocked if human input is needed.

Development

npm install
npm run check
npm run build

Publish on GitHub and npm

1. Create an empty GitHub repository named codex-claude-bridge-mcp, commit this project, and push the main branch.
2. Create an npm account, then run npm login and npm publish. If the package name is taken, rename the name field to an npm scope you own, such as @your-name/codex-claude-bridge-mcp.
3. Create a GitHub release and tag it with the same semantic version as package.json.

The package only publishes the compiled dist directory plus the README and MIT license. CI type-checks and builds every pull request.

After publishing to npm, users can register the package directly with their MCP clients using an npx -y <package-name> stdio command. The GitHub-clone installer remains the easiest supported setup because it registers both clients and a shared data directory in one step.

Security and privacy

Task text and messages are stored unencrypted in state.json under the chosen data directory. Do not point it to an untrusted network share and do not put secrets into messages. The data directory is intentionally excluded from Git.

License

MIT