# Codex ↔ Claude Code Bridge MCP

**English · [Türkçe](README.tr.md)**

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)

```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:

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

### macOS / Linux

```bash
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:

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

Set this environment variable for both registrations:

```text
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

```bash
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](LICENSE)