AgentBridge

中文文档

Local bridge for bidirectional communication between Claude Code and Codex inside the same working session.

The current implementation uses a two-process architecture:

• bridge.ts is the foreground MCP client started by Claude Code
• daemon.ts is a persistent local background process that owns the Codex app-server proxy and bridge state

This means the foreground MCP process can exit when Claude Code closes, while the background daemon and Codex proxy keep running. When Claude Code starts again, it can reuse the existing daemon automatically.

What this project is / is not

This project is:

• A local developer tool for connecting Claude Code and Codex in one workflow
• A bridge that forwards messages between an MCP channel and the Codex app-server protocol
• An experimental setup for human-in-the-loop collaboration between multiple agents

This project is not:

• A hosted service or multi-tenant system
• A generic orchestration framework for arbitrary agent backends
• A hardened security boundary between tools you do not trust

Architecture

┌──────────────┐          MCP stdio          ┌────────────────────┐
│ Claude Code  │ ───────────────────────────▶ │ bridge.ts          │
│ Session      │ ◀─────────────────────────── │ foreground client  │
└──────────────┘                              └─────────┬──────────┘
                                                        │
                                                        │ local control WS
                                                        ▼
                                              ┌────────────────────┐
                                              │ daemon.ts          │
                                              │ bridge daemon      │
                                              └─────────┬──────────┘
                                                        │
                                      ws://127.0.0.1:4501 proxy
                                                        │
                                                        ▼
                                              ┌────────────────────┐
                                              │ Codex app-server   │
                                              └────────────────────┘

Data flow

Loop prevention

Each message carries a source field ("claude" or "codex"). The bridge never forwards a message back to its origin.

Prerequisites

• Bun
• Claude Code v2.1.80+
• Codex CLI with the codex command available

Quick Start

# 1. Install dependencies
cd agent_bridge
bun install

# 2. Register the MCP server
# Merge .mcp.json.example into ~/.claude/.mcp.json and replace the path
# with your local absolute path:
#   "agentbridge": { "command": "bun", "args": ["run", "/absolute/path/to/agent_bridge/src/bridge.ts"] }

# 3. Start Claude Code and load AgentBridge as a channel (development mode)
claude --dangerously-load-development-channels server:agentbridge

Warning: --dangerously-load-development-channels loads a local development channel into Claude Code. This is currently a Research Preview workflow. Only enable channels and MCP servers you trust, because that local process can push messages into your Claude session and participate in the same workspace flow. AgentBridge is intended for local experimentation and development, not for untrusted environments.

bridge.ts checks whether a local daemon already exists before continuing.

• If no daemon exists, it starts daemon.ts
• If a daemon is already running, it reuses it

daemon.ts automatically spawns codex app-server in WebSocket mode and can surface the attach command through the Claude channel when needed.

# 4. Attach to the Codex proxy from another terminal to watch the Codex TUI
codex --enable tui_app_server --remote ws://127.0.0.1:4501

Note: the TUI connects to the bridge proxy port (default 4501), not the app-server port (4500). The bridge transparently forwards traffic and intercepts agentMessage.

Codex agentMessage items are pushed into the Claude session automatically. Claude can reply back through the reply tool.

File Structure

agent_bridge/
├── .github/
│   ├── ISSUE_TEMPLATE/       # Bug report and feature request templates
│   ├── pull_request_template.md
│   └── workflows/ci.yml      # GitHub Actions CI
├── assets/                    # Static assets (images, etc.)
├── src/
│   ├── bridge.ts             # Claude foreground MCP client that ensures the daemon exists and forwards messages
│   ├── daemon.ts             # Persistent background process that owns the Codex proxy and bridge state
│   ├── daemon-client.ts      # Foreground client for the daemon control WS
│   ├── control-protocol.ts   # Shared foreground/background control protocol
│   ├── claude-adapter.ts     # MCP server adapter for Claude Code channels
│   ├── codex-adapter.ts      # Codex app-server WebSocket proxy and message interception
│   └── types.ts              # Shared types
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── README.zh-CN.md
├── SECURITY.md
├── package.json
└── tsconfig.json

Configuration

Current Limitations

• Only forwards agentMessage items, not intermediate commandExecution, fileChange, or similar events
• Single Codex thread, no multi-session support yet
• Single Claude foreground connection; a new Claude session replaces the previous one

Codex git restrictions

Codex runs in a sandboxed environment that blocks all writes to the .git directory. This means Codex cannot run git commit, git push, git pull, git checkout -b, git merge, or any other command that modifies git metadata. Attempting these commands will cause the Codex session to hang indefinitely.

This restriction is especially relevant when Claude Code uses git worktrees — the worktree shares .git internals with the main repository, which can further tighten sandbox constraints.

Recommendation: Let Claude Code handle all git operations (branching, committing, pushing, creating PRs). Codex should focus on code changes and report completed work via agentMessage, then Claude Code takes care of the git workflow.

Roadmap

• v1.x (current): Improve the single-bridge experience without architectural refactoring — less noise, better turn discipline, and clearer collaboration modes. See docs/v1-roadmap.md.
• v2 (planned): Introduce the multi-agent foundation — room-scoped collaboration, stable identity, a formal control protocol, and stronger recovery semantics. See docs/v2-architecture.md.
• v3+ (longer term): Explore smarter collaboration, richer policies, and more advanced orchestration across runtimes.

How This Project Was Built

This project was built collaboratively by Claude Code (Anthropic) and Codex (OpenAI), communicating through AgentBridge itself — the very tool they were building together. A human developer coordinated the effort, assigning tasks, reviewing progress, and directing the two agents to work in parallel and review each other's output.

In other words, AgentBridge is its own proof of concept: two AI agents from different providers, connected in real time, shipping code side by side.

Contact

This is my first open-source project! I'd love to connect with anyone interested in multi-agent collaboration, AI tooling, or just building cool things together. Feel free to reach out:

• Twitter/X: @raysonmeng
• Xiaohongshu: Profile
• WeChat: Scan the QR code below to add me