by raysonmeng
A local bridge for bidirectional collaboration between Claude Code and Codex. 连接 Claude Code 与 Codex 的本地实时协作桥接工具。
# Add to your Claude Code skills
git clone https://github.com/raysonmeng/agent-bridgeLocal bridge for bidirectional communication between Claude Code and Codex inside the same working session.
AgentBridge uses a two-process architecture:
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.
This project is:
This project is not:
┌──────────────┐ 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 │
└────────────────────┘
No comments yet. Be the first to share your thoughts!
| 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 |
Each message carries a source field ("claude" or "codex"). The bridge never forwards a message back to its origin.
| 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.
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:
abgis a short alias foragentbridge. Both commands are identical — use whichever you prefer.
That's it. The daemon starts automatically when needed and reconnects if restarted.
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.
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
# 2. Set up local plugin + project config
agentbridge dev # Register local marketplace + install plugin
agentbridge init # Check dependencies, generate .agentbridge/config.json
# 3. Start Claude Code with AgentBridge plugin loaded
agentbridge claude
# 4. Start Codex TUI connected to the bridge (in another terminal)
agentbridge codex
Note:
agentbridge claudeinjects--dangerously-load-development-channels plugin:agentbridge@agentbridgeautomatically. This loads a local development channel into Claude Code (currently a Research Preview workflow). Only enable channels and MCP servers you trust.
After modifying AgentBridge source code, re-run agentbridge dev to sync changes to the plugin cache, then restart Claude Code or run /reload-plugins in an active session.
All commands work with both
agentbridgeand the short aliasabg.
| Command | Description |
|---------|-------------|
| abg init | Install plugin, check dependencies (bun/claude/codex), generate .agentbridge/config.json |
| abg claude [args...] | Start Claude Code with push channel enabled. Clears any killed sentinel from a previous kill. Pass-through args are forwarded to claude |
| abg codex [args...] | Start Codex TUI connected to AgentBridge daemon. Manages TUI process lifecycle (pid tracking, cleanup). Pass-through args forwarded to codex |
| abg kill | Gracefully stop both daemon and managed Codex TUI, clean up state files, write killed sentinel |
| abg dev | (Dev only) Register local marketplace + force-sync plugin to cache |
| abg --help | Show help |
| abg --version | Show version |
Some flags are automatically injected and cannot be manually specified:
agentbridge claude owns: --channels, --dangerously-load-development-channelsagentbridge codex owns: --remote, --enable tui_app_serverPassing these flags manually will result in a hard error with guidance to use the native command directly.
Running agentbridge init creates a .agentbridge/ directory in your project root:
| File | Purpose |
|------|---------|
| config.json | Machine-readable project config (Codex ports, turn coordination, idle shutdown) |
The config is loaded by the CLI and daemon at startup. Re-running init is idempotent and will not overwrite existing files.
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.)
├── docs/
│ ├── phase3-spec.md # Phase 3 design spec (CLI + Plugin)
│ ├── v1-roadmap.md # v1 feature roadmap
│ └── v2-architecture.md # v2 multi-agent architecture design
├── plugins/agentbridge/ # Claude Code plugin bundle
│ ├── .claude-plugin/plugin.json
│ ├── commands/init.md
│ ├── hooks/hooks.json
│ ├── scripts/health-check.sh
│ └── server/ # Bundled bridge-server.js + daemon.js
├── src/
│ ├── bridge.ts # Claude foreground MCP client (plugin entry point)
│ ├── daemon.ts # Persistent background daemon
│ ├── daemon-client.ts # WebSocket client for daemon control port
│ ├── daemon-lifecycle.ts # Shared daemon lifecycle (ensureRunning, kill, startup lock)
│ ├── control-protocol.ts # Foreground/background control protocol types
│ ├── claude-adapter.ts # MCP server adapter for Claude Code channels
│ ├── codex-adapter.ts # Codex app-server WebSocket proxy and message interception
│ ├── config-service.ts # Project config (.agentbridge/) read/write
│ ├── state-dir.ts # Platform-aware state directory resolver
│ ├── message-filter.ts # Smart message filtering (markers, summary buffer)
│ ├── types.ts # Shared types
│ ├── cli.ts # CLI entry point and command router
│ └── cli/
│ ├── init.ts # agentbridge init
│ ├── claude.ts # agentbridge claude
│ ├── codex.ts # agentbridge codex
│ ├── kill.ts # agentbridge kill
│ └── dev.ts # agentbridge dev
├── CLAUDE.md # Project rules for AI agents
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── README.zh-CN.md
├── SECURITY.md
├── package.json
└── tsconfig.json
| Variable | Default | Description |
|----------|---------|-------------|
| CODEX_WS_PORT | 4500 | Codex app-server WebSocket port |
| CODEX_PROXY_PORT | 4501 | Bridge proxy port for the Codex TUI |
| AGENTBRIDGE_CONTROL_PORT | 4502 | Control port between bridge.ts and daemon.ts |
| AGENTBRIDGE_STATE_DIR | Platform default | State directory for pid, status, logs (macOS: ~/Library/Application Support/agentbridge/, Linux: `