agentbridge

AgentBridge

中文文档

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

AgentBridge uses a two-process architecture:

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

When Claude Code closes, the foreground MCP process exits while the background daemon and Codex proxy keep running. When Claude Code starts again, it reconnects automatically with exponential backoff.

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 / plugin     ┌────────────────────┐
│ Claude Code  │ ──────────────────────────▶ │ bridge.ts          │
│ Session      │ ◀──────────────────────────  │ foreground client  │
└──────────────┘                             └─────────┬──────────┘
                                                       │
                                                       │ control WS (:4502)
                                                       ▼
                                             ┌────────────────────┐
                                             │ daemon.ts          │
                                             │ bridge daemon      │
                                             └─────────┬──────────┘
                                                       │
                                     ws://127.0.0.1:4501 proxy
                                                       │
                                                       ▼
                                             ┌────────────────────┐
                                             │ Codex app-server   │
                                             └────────────────────┘

Data flow

Direction	Path
Codex -> Claude	daemon.ts captures agentMessage -> control WS -> bridge.ts -> notifications/claude/channel
Claude -> Codex	Claude calls the reply tool -> bridge.ts -> control WS -> daemon.ts -> turn/start injects into the Codex thread

Loop prevention

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

Prerequisites

Dependency	Version	Install
Bun	v1.0+	curl -fsSL https://bun.sh/install | bash
Claude Code	v2.1.80+	npm install -g @anthropic-ai/claude-code
Codex CLI	latest	npm install -g @openai/codex

Note: Bun is required as the runtime for the AgentBridge daemon and plugin server. Node.js alone is not sufficient.

Quick Start

Install via Plugin Marketplace (recommended)

Install AgentBridge directly from Claude Code using the plugin marketplace:

# 1. In Claude Code, add the AgentBridge marketplace
/plugin marketplace add raysonmeng/agent-bridge

# 2. Install the plugin
/plugin install agentbridge@agentbridge

# 3. Reload plugins to activate
/reload-plugins

Then install the CLI tool:

# 4. Install the CLI globally
npm install -g @raysonmeng/agentbridge

# 5. Generate project config (optional)
abg init

# 6. Start Claude Code with AgentBridge channel enabled
abg claude

# 7. Start Codex TUI connected to the bridge (in another terminal)
abg codex

Tip: abg is a short alias for agentbridge. Both commands are identical — use whichever you prefer.

That's it. The daemon starts automatically when needed and reconnects if restarted.

Updating the plugin

When a new version is released, update from Claude Code:

/plugin marketplace update agentbridge
/reload-plugins

Or enable auto-update: run /plugin → Marketplaces tab → select agentbridge → Enable auto-update.

Install for local development

If you want to modify AgentBridge source code, use the local development setup instead:

# 1. Clone and install dependencies
git clone https://github.com/raysonmeng/agent-bridge.git
cd agent-bridge
bun install
bun link