AgentBridge

中文文档

🌐 Website: raysonmeng.github.io/agent-bridge, with an animated replay of a real session.

Discussed on LINUX DO — the developer community. / 在 LINUX DO 开发者社区交流。

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

What that buys you, concretely:

• Cross-review — Codex implements; Claude reviews the diff inside the same session and pushes change requests straight back into Codex's thread. Two providers check each other's work without copy-paste.
• Task splits from one prompt — ask either agent to propose a division of labor with the other, and they negotiate who does what before writing code. You steer; they coordinate.
• Quota relay for overnight runs — when one side's subscription window runs dry, it stops cleanly at a turn boundary and hands the task off to the other side, so a long job keeps moving instead of dying at a limit.

This tool was largely built by Claude Code and Codex collaborating through it. Every PR written by one agent was reviewed by the other. AgentBridge is its own proof of concept.

⭐ If AgentBridge is useful to you, a star helps other people running two agents find it.

Why not just…

• …run two terminals and copy-paste? You can, but then you are the message bus: you ferry text by hand and guess when it is safe to interrupt. AgentBridge automates the relay: messages flow on their own, a busy-guard blocks replies during an active turn, and the bridge filters noisy intermediate events so each side sees only the other's meaningful output.
• …use a one-way delegation plugin? Tools like openai/codex-plugin-cc let a host call Codex and get one answer back: request in, response out, no standing peer on the other side. AgentBridge keeps both agents live as persistent peers, and either side can push a message mid-turn (a review comment lands while the other is still working), not only at call boundaries.
• …wire up an external orchestrator? A god-process scheduling dumb terminals is top-down: one brain, N workers that never talk to each other. AgentBridge is peer-to-peer: two full agents converse in-session, propose their own splits, and review each other, with the human steering instead of scripting every hop.

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 — the daemon intercepts Codex output and pushes it to Claude as channel notifications; Claude replies via the reply MCP tool, and the bridge injects the reply 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.

Context handling — real-time, without the context blowing up

A common worry about real-time bidirectional messaging is that the two agents' contexts merge and grow without bound. They don't. The bridge passes messages, not context — each agent keeps its own context window, and the bridge never copies one agent's full transcript into the other. (And which agent plans vs executes is your call — the roles aren't fixed; Codex can drive Claude just as easily.) Three filters keep what actually crosses small:

1. Only agentMessage crosses. The bridge forwards an agent's actual conclusions, not its tool-call noise — commandExecution, fileChange, and reasoning deltas never reach the other side, nor does its full scrollback.
2. Three-tier marker routing (default filtered mode). Each message is tagged and the daemon routes by tag: [IMPORTANT] forwards immediately, [STATUS] is buffered and batched into one periodic summary (default: 3 updates or 15s), [FYI] is dropped. The marker rules live once in the project's AGENTS.md (written by abg init), loaded at agent startup.
3. The collaboration contract lives once in AGENTS.md, not appended to every message (which would pollute every thread and its resume title).

Net effect: each side receives a curated stream of meaningful messages, so context grows with the number of real exchanges — not the other agent's raw activity. Set AGENTBRIDGE_FILTER_MODE=full (or the config equivalent) when you do want the unfiltered stream.

Prerequisites

Claude Code and Codex recommendations are the publishers' latest stable npm versions checked on 2026-09-12. These recommendations do not change the existing minimum-version checks. Cross-machine Codex messaging, acknowledgements and daemon/session recovery were also verified with Codex 0.153.4. For room setup and the one-time --new step after upgrading, see Codex remote rooms.

Bun is required as the runtime for the AgentBridge daemon and plugin server. Node.js alone is not enough. If abg installs but won't run, install Bun first (see Troubleshooting).

Quick Start

Five steps from nothing to a running pair:

# 1. Install Bun (the runtime; Node alone won't work)
curl -fsSL https://bun.sh/install | bash

# 2. Install the CLI. postinstall auto-registers the Claude Code plugin
#    marketplace AND installs the plugin (best-effort; needs bun + claude present).
npm install -g @raysonmeng/agentbridge

# 3. Initialize the project (check deps, install plugin if needed, write .agentbridge/config.json)
abg init

# 4. Start Claude Code with the AgentBridge channel enabled
abg claude

# 5. In another terminal, start Codex TUI connected to the same bridge
abg codex

That's it: the daemon starts automatically when needed and reconnects if restarted. (abg is a short alias for agentbridge; both are identical.) If the postinstall plugin step was skipped (e.g. Claude Code wasn't installed yet), run abg init to retry it, or see the manual install fallback.

[!WARNING] abg claude launches with --dangerously-skip-permissions and abg codex launches with --yolo by default. This is deliberate: an unattended agent pair can't stop to ask you for each permission. It means both agents can run commands and edit files without prompting. Only do this in a workspace you trust. To launch with normal prompts, add --safe (abg claude --safe, abg codex --safe) or set AGENTBRIDGE_SAFE=1. The defaults are also auto-suppressed if you pass your own permission flags.

Your first collaboration

With both sides running, give Claude a task that wants a second agent, e.g.:

Ask Claude: "Propose a task split with Codex for <your task>, then have Codex implement its part while you review."

You should see Claude send a proposed division of labor into Codex's session, Codex accept (or counter) and start working, and Codex's completion push back into Claude's session for review, without you relaying anything by hand.

Manual plugin install (fallback)

If the automatic postinstall didn't register the plugin, do it from inside Claude Code:

# 1. 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

T