AgentBridge: a local relay between Claude Code and Codex

The problem AgentBridge solves, and for whom

Running Claude Code and Codex on the same task usually means two terminals and a human in the middle. You copy a diff from one, paste it into the other, guess when it is safe to interrupt, and lose the thread of who asked what. AgentBridge replaces the human relay with a local daemon that carries messages between the two agents while both stay alive.

The README frames the audience narrowly: a local developer tool for connecting Claude Code and Codex in one workflow, an experimental setup for human-in-the-loop collaboration. It explicitly is not a hosted service, not a generic orchestration framework for arbitrary agent backends, and not a hardened security boundary. That last line matters. If your threat model includes one agent doing something hostile, this is the wrong tool by the author's own description.

The concrete payoff the README lists is threefold: cross-review where Codex implements and Claude reviews the diff inside the same session and pushes change requests back; task splits negotiated from a single prompt before any code is written; and quota relay, where one side stops at a turn boundary when its subscription window runs dry and hands the task to the other. The project itself was built this way. The README states that every PR written by one agent was reviewed by the other.

How the bridge moves messages without merging contexts

The mechanism is a persistent background daemon that sits between an MCP channel and the Codex app-server protocol. Codex output is intercepted and pushed to Claude as channel notifications. Claude answers through a `reply` MCP tool, and the bridge injects that reply into the Codex thread as a `turn/start`. Delivery is push-first: if a push fails, the message falls back to an in-memory queue that `get_messages` drains. A per-message `source` field prevents loops.

The most interesting design decision is what does not cross. The README is direct that the bridge passes messages, not context. Each agent keeps its own context window, and no full transcript is copied from one side to the other. Three filters enforce that.

Only `agentMessage` payloads are forwarded. Tool-call noise, `commandExecution`, `fileChange` and reasoning deltas never reach the other side. On top of that sits a three-tier marker routing scheme, defaulting to `filtered` mode: `[IMPORTANT]` forwards immediately, `[STATUS]` is buffered and batched into one periodic summary, and `[FYI]` is dropped. The batching defaults are three updates or fifteen seconds. The marker rules live in the project's `AGENTS.md`, written by `abg init` and loaded at agent startup, so the contract is defined once instead of being appended to every message. Setting `AGENTBRIDGE_FILTER_MODE=full` restores the unfiltered stream.

Turn coordination is handled by a busy-guard that rejects replies during an active Codex turn, plus a per-turn inactivity watchdog that stops a lost `turn/completed` from locking injection permanently. That watchdog is the kind of detail that suggests the author hit the failure in practice. The README does not describe what happens if the watchdog itself misfires.

Installing AgentBridge with Bun and running a first pair

The README lists Bun v1.3.11 or later as a prerequisite, alongside Claude Code and the Codex CLI. Bun is the runtime, and `package.json` pins `packageManager` to `bun@1.3.11` with an `engines` field requiring `>=1.3.11`. Install Bun first if you do not have it:

curl -fsSL https://bun.sh/install | bash

The package ships two binaries, `agentbridge` and `abg`, both pointing at `dist/cli.js`. Once installed, `abg init` is the step that writes the collaboration contract into the project's `AGENTS.md`, which is then loaded at agent startup. The README describes `abg doctor` as read-only diagnostics, which is the sensible first command to run when something looks wrong.

abg init
abg doctor

Multiple pairs can run side by side, one Claude plus Codex pair per project directory, with ports allocated per pair in steps of +10 starting at 4500. Pair-aware subcommands (`claude`, `codex`, `resume`, `kill`, `doctor`, `budget`) accept a `--pair` flag. A bare `abg codex` resumes the pair's last Codex thread, and `abg resume` prints or performs the resume commands for both sides. The repository also ships `.mcp.json.example` as a starting point for MCP configuration.

The daemon is designed to survive Claude Code restarts with auto-reconnect and backoff, and `abg pairs prune` reclaims stranded state. The README does not document a rollback path for the `AGENTS.md` file that `abg init` writes, so keep that file under version control before running init.

Where AgentBridge is the wrong tool

The README's own list of non-goals is the clearest limitation. It is not a hardened security boundary between tools you do not trust. Two agents exchanging instructions across a local daemon, with one able to inject a `turn/start` into the other, is a trust relationship, not a sandbox. If you need isolation, this is not it.

It is also not a generic orchestrator. The bridge is written against the Codex app-server protocol and an MCP channel, and the README says plainly it is not a framework for arbitrary agent backends. Adding a third provider is not a configuration change.

The version number is the other honest signal. The latest release is v0.1.31, published on 2026-09-12, and the previous two releases before it were both on 2026-07-03. The last push to the repository was on 2026-09-13. That is a fast-moving pre-1.0 project, and the interface surface (`abg` subcommands, environment variables, the `AGENTS.md` contract) should be expected to move with it.

Finally, the quota relay feature depends on subscription windows running dry. If you are on metered API billing rather than a subscription, that mechanism has nothing to act on, and the budget coordination section of the README is largely irrelevant to you.

How AgentBridge differs from a one-way delegation plugin

The README names `openai/codex-plugin-cc` as the closest alternative and draws the distinction precisely. A one-way delegation plugin lets a host call Codex and get one answer back: request in, response out. There is no standing peer on the other side. AgentBridge keeps both agents live as persistent peers, and either side can push a message mid-turn, so a review comment can land while the other agent is still working rather than only at a call boundary.

The second comparison the README makes is against an external orchestrator. A god-process scheduling dumb terminals is top-down: one brain and N workers that never talk to each other. AgentBridge is peer-to-peer, with two full agents conversing in-session, proposing their own splits, and reviewing each other, while the human steers instead of scripting every hop.

That difference has a cost. A one-way plugin has a single call boundary, which makes reasoning about state trivial. A peer-to-peer bridge has two live agents, a busy-guard, a watchdog, and a fallback queue, and every one of those is a place where a turn can get stuck. The README addresses the stuck-turn case with the watchdog, but the complexity is real and is the price of mid-turn delivery.

Licence, maintenance and upgrade cost

AgentBridge is MIT licensed, and the repository carries a `LICENSE` file plus a `CLA.md` for contributions. MIT is permissive: you can use, modify and redistribute it, including commercially, provided the copyright notice and permission notice are preserved. The repository also includes `SECURITY.md` and `CODE_OF_CONDUCT.md`. None of that is legal advice; read the licence text yourself if the terms matter to your organisation.

On maintenance, the last push was on 2026-09-13, three days before this writing, and the repository is not archived. The release cadence shows a gap: v0.1.29 and v0.1.30 both landed on 2026-07-03, then v0.1.31 on 2026-09-12, roughly ten weeks later. That is a bursty schedule rather than a steady one, which is normal for a single-maintainer project but worth knowing if you are pinning a version.

The upgrade cost sits mostly in `AGENTS.md`. Because the collaboration contract is written once by `abg init` and loaded at agent startup, a change to the marker routing rules or the expected message format means regenerating or hand-editing that file in every project directory where you have run init. The `prepublishOnly` script runs `build:cli`, `build:plugin`, `verify:plugin-sync` and `check-plugin-versions.js`, which suggests the CLI and plugin bundles are versioned together and should be upgraded as a set rather than independently.

Editorial conclusion

Adopt AgentBridge if you already run Claude Code and Codex side by side and want cross-review without copy-paste, and you accept a v0.1.x tool maintained by one developer. Do not adopt it as a security boundary between untrusted tools, a hosted service, or a generic orchestrator for other agent backends; the README rules those out. Before relying on it, verify that the BusyGuard and watchdog behave under a killed turn in your own setup, and confirm the port stride of 4500 does not collide with anything already listening.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. raysonmeng/agent-bridge on GitHub
4. README
5. Releases