# AgentBridge keeps both agents live as peers, and filters what crosses between them

> A local bridge that lets Claude Code and Codex talk inside one working session, so a review can land mid-turn instead of at a call boundary. Context is not merged, three marker tiers decide what gets forwarded, and the project states plainly what it is not.

**raysonmeng/agent-bridge** — A local bridge for bidirectional collaboration between Claude Code and Codex. 连接 Claude Code 与 Codex 的本地实时协作桥接工具。

- Repository: https://github.com/raysonmeng/agent-bridge
- Website: https://raysonmeng.github.io/agent-bridge/
- Stars: 368 · Forks: 60
- Language: TypeScript
- License: MIT
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/raysonmeng-agent-bridge

## Peer to peer, with the human steering rather than scripting each hop

The design position is stated as a contrast with three alternatives.

Against running two terminals and pasting text, the argument is that the human becomes the message bus: ferrying messages by hand and guessing when it is safe to interrupt. The bridge automates that relay instead, so messages flow on their own, a busy-guard blocks replies during an active turn, and noisy intermediate events are filtered so each side sees only the other's meaningful output.

Against a one-way delegation plugin such as openai/codex-plugin-cc, the argument is about standing peers. Those tools let a host call Codex and get one answer back: request in, response out. Here both agents stay live as persistent peers, and either side can push a message mid-turn, so a review comment lands while the other is still working rather than only at a call boundary.

Against an external orchestrator, the argument is top-down against peer-to-peer. A god process scheduling dumb terminals gives one brain and N workers that never talk to each other. Here two full agents converse in-session, propose their own division of labour and review each other.

Which agent plans and which executes is not fixed. Codex can drive Claude as easily as the reverse.

## Messages cross, context does not

The stated fear about real-time bidirectional messaging is that the two contexts merge and grow without bound. The answer is that the bridge passes messages rather than context: each agent keeps its own context window, and the full transcript of one is never copied into the other.

Three filters keep what does cross small.

First, only agentMessage payloads cross. An agent's actual conclusions are forwarded, while commandExecution events, fileChange events and reasoning deltas never reach the other side, and neither does its scrollback.

Second, a three-tier marker routing system runs in the default filtered mode. Each message is tagged and the daemon routes by tag: an IMPORTANT message forwards immediately, a STATUS message is buffered and batched into one periodic summary at three updates or fifteen seconds, and an FYI message is dropped. Those marker rules are written once into the project's AGENTS.md by abg init and loaded at agent startup.

Third, the collaboration contract itself lives once in that file rather than being appended to every message, which would otherwise pollute every thread and its resume title.

Setting the environment variable to full, or the config equivalent, restores the unfiltered stream when that is what you want.

## A busy-guard, a watchdog and a source field keep the loop closed

The mechanics of delivery are specific enough to reason about.

On the Codex side, the daemon intercepts Codex output and pushes it to Claude as channel notifications. On the Claude side, a reply goes back through the reply MCP tool, and the bridge injects it into the Codex thread as a turn/start.

Delivery has a fallback. Messages arrive as channel notifications, and a failed push falls back to an in-memory queue that get_messages drains. Loop prevention comes from a source field carried on each message rather than from a heuristic about content.

Turn coordination has two guards. The busy-guard rejects replies while a Codex turn is active, which is the direct answer to the interrupted-workspace problem. A per-turn inactivity watchdog stops a lost turn/completed from locking injection forever, which is the failure mode that would otherwise leave a pair wedged with nowhere to send anything.

Noisy intermediate events are collapsed on the way through, so the payload that reaches Claude is a meaningful agent message rather than a stream of tool activity.

## Ports move in strides of ten from 4500, one pair per directory

Several pairs can run side by side, with one Claude and Codex pair per project directory.

Ports are allocated per pair in strides of ten starting from 4500, which is a simple scheme with a useful property: the port encodes which pair it belongs to, so a stray process can be traced back to a directory without a lookup table.

The CLI is pair-aware. The commands for claude, codex, resume, kill, doctor and budget all take a --pair flag, so the same binary operates on the right pair rather than guessing from the working directory.

The lifecycle is built to survive the host rather than the session. A persistent background daemon outlives a Claude Code restart and reconnects with backoff, orphan processes are cleaned up, abg doctor gives read-only diagnostics, and abg pairs prune reclaims stranded state left behind by a killed pair.

Thread state is recoverable too. A bare abg codex resumes that pair's last Codex thread, and abg resume prints, or performs, the resume commands for both sides, which is what makes an interrupted long run restartable rather than lost.

## A quota wall becomes a handoff at a turn boundary

The feature aimed at overnight work is budget coordination, described together with a slowdown line and fully automatic resume.

The mechanism is deliberately conservative. 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.

Stopping at a turn boundary rather than mid-turn is the important part. A handoff in the middle of a turn would leave the receiving agent with a partial action to reason about, whereas a boundary gives it a finished unit of work and a clean place to continue from.

The same script surface exposes budget as a per-pair command, so the budget state belongs to a pair rather than to a global session.

That capability is what makes the bridge useful across a provider boundary rather than only within one. Two subscriptions become one continuous budget as long as the task can be split into turns, which is the normal shape of agent work.

## Bun is the runtime, and both agent CLIs are pinned to a checked day

Three prerequisites, each with a recommended version and an install command.

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

```bash
npm install -g @anthropic-ai/claude-code@2.1.269
```

```bash
npm install -g @openai/codex@0.154.0
```

Bun is required at 1.3.11 or newer, and the package manifest declares both a packageManager field and a Bun engine floor at the same version.

The two agent versions are worth reading carefully. The stated basis for them is the publishers' latest stable npm releases as checked on 2026-09-12, and the documentation is explicit that these recommendations do not change the existing minimum-version checks. So the pins are advice rather than enforcement, and a newer stable release of either CLI will not by itself break the bridge.

The published package is scoped, carries version 0.1.31, and installs two bin names for the same entry point, so agentbridge and abg are interchangeable.

## The project states what it is not, including a security boundary

Three things are ruled out in the project's own words, and the third is the one that matters most in a review.

It is not a hosted service or a multi-tenant system. It is not a generic orchestration framework for arbitrary agent backends, since it speaks to two specific peers. And it is not a hardened security boundary between tools you do not trust.

That last exclusion is a design statement rather than a missing feature. The bridge forwards model output from one agent into the other's context, which is exactly the path where untrusted tool output becomes instructions to a trusted model.

The repository is shaped like a personal tool with more surface than that suggests: a Claude plugin directory, a Cursor rules file and directory, an opencode configuration, a Kiro directory, windsurf rules, a Gemini instruction file, multiple agent instruction files, Docker files, a site directory and an example Tailscale ACL. The breadth reflects the number of editors the author works in, not the number of peers the bridge supports.

The default branch is master rather than main, and the last commit on it is dated 2026-09-30.

## Conclusion

AgentBridge fits one person running both agents on the same repository who wants a second opinion without being the message bus, especially when a subscription window may run out mid-task. It does not fit a team needing a hosted service, a general orchestrator for arbitrary backends, or a security boundary between tools you do not trust, since the project rules out all three explicitly. Two caveats to weigh: the marker tiers mean a message tagged FYI is dropped rather than delivered, and the recommended Claude Code and Codex versions are pinned to what was checked on 2026-09-12 rather than tracked automatically. Read the AGENTS.md the init writes, since that file is where the routing rules actually live.

## FAQ

### What exactly does AgentBridge connect?

Claude Code and Codex inside one local working session, by forwarding messages between an MCP channel and the Codex app-server protocol. Codex output is pushed to Claude as channel notifications and Claude replies through the reply MCP tool, which the bridge injects as a turn/start.

### Does AgentBridge merge the two agents' context windows?

No. The bridge passes messages rather than context: each agent keeps its own window and one agent's full transcript is never copied into the other. Only agentMessage payloads cross, not command or file-change events, reasoning deltas or scrollback.

### What do the IMPORTANT, STATUS and FYI markers do in AgentBridge?

In the default filtered mode they route delivery: IMPORTANT forwards immediately, STATUS is buffered and batched into one periodic summary at three updates or fifteen seconds, and FYI is dropped. The rules live once in the project's AGENTS.md, written by abg init.

### How does AgentBridge avoid a message loop between the agents?

Loop prevention uses a source field carried on each message. A busy-guard also rejects replies while a Codex turn is active, and a per-turn inactivity watchdog stops a lost turn/completed from blocking injection permanently.

### What are the prerequisites for running AgentBridge?

Bun v1.3.11 or newer, Claude Code 2.1.269 and Codex CLI 0.154.0. The agent versions are the publishers' latest stable npm releases checked on 2026-09-12, and those recommendations do not change the existing minimum-version checks.

### What is AgentBridge explicitly not designed to be?

Not a hosted service or multi-tenant system, not a generic orchestration framework for arbitrary agent backends, and not a hardened security boundary between tools you do not trust.

## Sources

- [License: MIT](https://github.com/raysonmeng/agent-bridge/blob/master/LICENSE)
- [Project website](https://raysonmeng.github.io/agent-bridge/)
- [raysonmeng/agent-bridge on GitHub](https://github.com/raysonmeng/agent-bridge)
- [README](https://github.com/raysonmeng/agent-bridge/blob/master/README.md)
- [Releases](https://github.com/raysonmeng/agent-bridge/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/raysonmeng-agent-bridge