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
Features
- Bidirectional Claude ↔ Codex messaging in one working session — Codex output is intercepted and pushed to Claude as channel notifications; Claude replies via the
reply MCP tool, injected into the Codex thread as a turn/start.
- Push delivery with fallback — messages arrive as channel notifications; a failed push falls back to an in-memory queue drained by
get_messages. Loop prevention via the per-message source field.
- Turn coordination — a busy-guard rejects replies during an active Codex turn; a per-turn inactivity watchdog stops a lost
turn/completed from locking injection forever; noisy intermediate events are collapsed so only meaningful agentMessage payloads reach Claude.
- Multiple pairs side by side — one Claude+Codex pair per project directory, ports allocated per pair in +10 strides from 4500. Pair-aware
claude / codex / resume / kill / doctor / budget via --pair.
- Resilient lifecycle — a persistent background daemon survives Claude Code restarts (auto-reconnect with backoff); orphan-process cleanup;
abg doctor read-only diagnostics; abg pairs prune reclaims stranded state.
- Thread auto-resume — bare
abg codex resumes the pair's last Codex thread; abg resume prints/performs the resume commands for both sides.
- Budget coordination, slowdown-line & fully-automatic resume — keep a long task moving across subscription-quota windows instead of dying at a limit. See Budget Coordination & Auto-Resume.
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 |
