agent-bridge

AgentBridge is a local development tool used to connect Claude Code and Codex within the same working session, enabling bidirectional real-time collaboration. It is not a hosted service, nor a general-purpose orchestration framework, but rather an experimental multi-agent setup for human-machine collaboration.

Uses

• Cross-review: Codex implements code, Claude reviews the diff within the same session, and pushes modification requests directly back into Codex's thread; the two providers check each other without copy-pasting.
• Single-prompt division of labor: ask either agent to propose a division of labor with the other; the two negotiate their respective parts before writing code, with the user steering direction.
• Quota relay: when one party's subscription window is exhausted, stop cleanly at a turn boundary and hand off the task at hand to the other party, so long tasks keep running rather than failing at the limit.

Main capabilities

• Bidirectional messaging: 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 turn/start.
• Push delivery and fallback: messages arrive as channel notifications; when push fails, they fall back to an in-memory queue and are retrieved by get_messages; looping is prevented via each message's source field.
• Turn coordination: the busy-guard rejects replies while a Codex turn is active; a per-turn inactivity watchdog prevents a lost turn/completed from permanently locking injection; noisy intermediate events are collapsed so that only meaningful agentMessages reach Claude.
• Multiple parallel pairs: one Claude+Codex pair per project directory, with ports allocated starting at 4500 in steps of +10; pair-aware commands support claude, codex, resume, kill, doctor, and budget used together with --pair.
• Lifecycle resilience: a persistent background daemon can survive Claude Code restarts and automatically reconnect (with backoff); it supports orphan process cleanup, abg doctor read-only diagnostics, and abg pairs prune to reclaim stranded state.
• Automatic thread recovery: running abg codex directly recovers that pair's last Codex thread; abg resume prints or executes both parties' recovery commands.
• Budget coordination and automatic recovery: with the companion tool agent-quota-guard implements slow lines and automatic continuation across subscription quota windows.

Context handling The bridge only passes messages, not context: each agent keeps its own context window, and the bridge does not copy one agent's full record to the other. Only agentMessage crosses the boundary; commandExecution, fileChange, and reasoning deltas do not reach the other side, and full rollback records are not passed either. In the default filter mode, three-level tag routing is used: [IMPORTANT] is forwarded immediately, [STATUS] is buffered and summarized in batches (by default 3 updates or 15 seconds), and [FYI] is discarded. The tagging rules are written only in the project's AGENTS.md (written by abg init) and are loaded when the agent starts. Set AGENTBRIDGE_FILTER_MODE to full (or the corresponding configuration) to get an unfiltered stream.

Usage Bun is required as the runtime for the AgentBridge daemon and plugin server; Node.js alone is not enough. If abg cannot run after installation, install Bun first. The basic process is: after installation, run abg init to initialize, then start abg claude and abg codex separately (abg is the short alias for agentbridge; the two are equivalent). abg claude starts by default with --dangerously-skip-permissions, and abg codex starts by default with --yolo, meaning both can run commands and edit files without prompting, and should only be used in trusted workspaces; if normal permission prompts are needed, add --safe, or set AGENTBRIDGE_SAFE=1. These defaults are also automatically suppressed when custom permission flags are passed in. abg claude has the --channels and --dangerously-load-development-channels flags; abg codex has the --remote and --enable tui_app_server flags; manually passing these exclusive flags will cause an error and prompt you to use the native commands directly. Architecturally, it consists of two processes: bridge.ts is the foreground MCP client started by Claude Code through the AgentBridge plugin, and exits when Claude Code closes; daemon.ts is a persistent local background processprocess, the single source of truth for the Codex app-server proxy and bridge state, survives Claude Code restarts, and bridge.ts reconnects with exponential backoff. Running agentbridge init creates the .agentbridge/ directory in the project root; configuration is loaded by the CLI and the daemon at startup; running init repeatedly is idempotent and does not overwrite existing files. The daemon stores runtime state in a platform-aware directory, including daemon.pid, status.json, agentbridge.log, killed (sentinel), and startup.lock.

Use cases

• Small-to-medium development tasks that require cross-validation of code by two providers.
• Collaborative development where a single prompt triggers the agents to negotiate the division of labor themselves.
• Automated tasks that need to run for a long time and keep progressing across subscription quota windows.
• Local development environments with multiple pairs of agents running in parallel across multiple project directories.

Limitations

• Only agentMessage is forwarded; intermediate events such as commandExecution and fileChange are not forwarded.
• Only a single Codex thread per pair; multi-session within a pair is not yet supported.
• Only a single Claude foreground connection per pair; a new Claude session replaces the previous one.
• Multiple pairs can run in parallel on the same machine (one pair per project directory), but Windows is not yet an officially supported platform.
• Automatic recovery is an experimental optional feature and depends on the companion guard; recovery on the Claude side is best-effort and is only marked as recovered after a real ack_resume is received.
• It is not a hosted service, a multi-tenant system, a general-purpose orchestration framework, nor a hardened security boundary between untrusted tools.

Cross-network collaboration (v3 preview) Version 0.1.31 provides a cross-machine shared-room collaboration layer that runs through a broker and includes the auth, broker, room, join, and publish commands; Codex-only machines can use the native room tools to exchange messages and acknowledgments. Setup and delivery limitations are detailed in the user manual.

Update notification abg claude and abg codex print a one-line notice to stderr when a new stable version is released; the check is best-effort, uses cached results, runs in the background at most once per day, and silently ignores network failures. In an interactive TTY, it prompts whether to upgrade, and ignores theversion if there is no response within 15 seconds. It can be disabled with NO_UPDATE_NOTIFIER=1, or use AGENTBRIDGE_UPDATE_PROMPT=0 to keep only the notification.