local bridge · claude code ⇄ codex

Multi AI agents. In-session comms.
No copy-paste.

AgentBridge is a local bridge that lets Claude Code and Codex collaborate in real time inside one working session: they cross-review each other's diffs, split tasks between them, and relay work across quota limits.

npm install -g @raysonmeng/agentbridge

MIT·runs 100% locally·zero runtime deps·1,700+ tests·v0.1.25

what that buys you

Three workflows

Two full agents from different providers check each other's work while you steer. Hover a card for the full exchange.

Cross-review, inside the session

Codex implements; Claude reviews the diff in real time inside the same session and pushes change requests straight back into Codex's thread. Two providers check each other's work without copy-paste.

cross-review
codex  → guard done, 3 files
claude → reviewing diff…
claude → reply: unbounded retry
codex  → fixed — capped at 5
cross-review — full exchange
you    → have Codex add rate limiting to the API client
claude → task sent to Codex over the bridge
codex  → token-bucket limiter implemented — 3 files changed
claude → reviewing the diff mid-session…
claude → reply: retry loop after 429 has no upper bound;
         a flaky upstream turns this into an infinite loop
codex  → good catch — capped at 5, exponential backoff
claude → re-reviewed ✓ approved. Two providers, zero 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.

task-split
you    → split the refactor?
claude → I take tokens+tests,
         Codex middleware. OK?
codex  → agreed — starting now
task-split — full exchange
you    → propose a split with Codex for the auth refactor
claude → plan: I take the token model + its tests;
         Codex rewrites the middleware layer. Agreed?
codex  → agreed — starting middleware now
claude → token model done — pushing interface notes to Codex
codex  → middleware done; using Claude's new TokenClaims type
claude → both halves merged. One prompt, two agents, no relay.

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, so the job keeps moving instead of dying at the limit.

quota-relay
codex  → 5h window low
bridge → checkpoint written,
         handing to Claude…
claude → resumed from ckpt
bridge → resumes Codex later
quota-relay — full exchange
codex  → 5h window at 4% — finishing current turn cleanly
bridge → checkpoint written → .agent/checkpoint.md
bridge → task handed to Claude, context preserved
claude → resumed from checkpoint — continuing the migration
         ⏳ two hours later — window refreshed
bridge → Codex quota refreshed — auto-resume queued
codex  → picking the task back up in the original TUI
claude → overnight run survived two quota walls. Zero babysitting.

Multi-pair by design

Every project folder gets its own pair. Working three repos at once? Run three bridges side by side; the CLI allocates ports per pair, and --pair <name> targets a specific one.

multi-pair
~/work/shop   → pair 1  claude ⇄ codex  :4510
~/work/api    → pair 2  claude ⇄ codex  :4520
~/oss/bridge  → pair 3  claude ⇄ codex  :4530

quota relay

The part nothing else does

A long task shouldn't die because one agent hit its 5-hour or weekly subscription limit at 2am. AgentBridge keeps it moving.

No mid-task cut

Near the quota hard-line, the companion agent-quota-guard does not deny mid-tool-call. It lets the current turn finish, stops cleanly at the boundary, writes a .agent/checkpoint.md, and drops a pending record the bridge detects.

Automatic resume

When the paused side's window refreshes, the bridge resumes the task in the original interactive TUI: Codex via a queued turn/start, Claude via a channel push it acks with ack_resume. Idempotency tombstones inject each resume at most once.

Both windows in one glance

The daemon polls both agents' account-level 5h and weekly quota. abg budget --json prints the live snapshot: both windows, drift between the two sides, and pause state.

Opt-in. Quota relay ships as a companion-guard feature. Install agent-quota-guard to enable it. Without it, everything else still works.

positioning

Why AgentBridge, and not…

Three things people reach for instead, and the work each one hands back to you.

  AgentBridge Two terminals + copy-paste One-way delegation plugin
(e.g. codex-plugin-cc)		 External orchestrator
Message relay Automatic, both ways You are the message bus Request in, response out Scripted per hop
Native CLI capabilities preserved Fully — both are the real, unmodified CLIs Yes — but you are the glue Partly — callee runs as a one-shot subprocess No — agents become driven workers
Both agents live as peers Yes — persistent peers Yes, but disconnected No — one standing host, one callee No — one brain, N dumb workers
Push mid-turn Yes — review lands mid-turn Manual, guess when it's safe Only at call boundaries Only at scheduled steps
Agents propose their own splits Yes — they negotiate No No No — top-down
Survives a quota limit Yes — checkpoint + auto-resume No — you restart by hand No Depends on your script

quick start

Five steps to a running pair

The daemon starts automatically when needed and reconnects if restarted.

01

Install Bun (the runtime; Node alone won't work)

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

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
03

Initialize the project

Checks dependencies (bun/claude/codex), installs the plugin if the postinstall skipped it, and writes .agentbridge/config.json. Run once per project.

abg init
04

Start Claude Code with the AgentBridge channel

abg claude
05

In another terminal, start Codex connected to the same bridge

abg codex

Your first collaboration: with both sides running, ask Claude — "Propose a task split with Codex for <your task>, then have Codex implement its part while you review." You'll see the split flow into Codex's session, Codex start working, and its completion push back to Claude for review, without you relaying anything by hand.

abg is a short alias for agentbridge. Both agents launch with max-permission defaults so an unattended pair doesn't stop for each prompt. Add --safe for normal prompts. See the Troubleshooting guide if abg installs but won't run.

origin

AgentBridge is its own proof of concept

We did not build it the normal way.

This tool was largely built by Claude Code (Anthropic) and Codex (OpenAI) collaborating through it, the very bridge they were building together. Every PR written by one agent was reviewed by the other. A human steered: assigning tasks, reviewing progress, and directing the two to work in parallel and check each other's output.

Two AI agents from different providers, connected in real time, shipping code side by side and reviewing each other's PRs across the wire. The commit history shows it.

roadmap

Claude Code ↔ Codex ships today. Here's what's coming.

Testing now · in branch

Multi-machine agent network

Agents on different machines joining one room over your LAN or tailnet: passphrase-gated, with presence and a shared whiteboard. Already passing real three-machine cross-network tests behind experimental abg room / join / broker commands.

Next · public vote

More agents on the bridge

OpenCode, Gemini CLI, openclaw, hermes, wired in one adapter at a time, each a first-class peer. Which one lands first is your call: vote on issue #212.

Designing

Capability mesh

From exchanging messages to calling each other's abilities: every bridged agent publishes its commands, skills and MCP tools; peers invoke them directly, behind a default permission gate. Chat bridge → agent bus.

Ongoing

Sharper collaboration

Less noise, better turn discipline, richer coordination policies, and stronger recovery semantics across runtimes.

faq

Questions people ask

Real-time messaging — won't the context explode?

No, because the bridge passes messages, not context. Each agent keeps its own context window; the bridge never copies one agent's full transcript into the other. And which agent plans vs executes is your call — the bridge doesn't hard-code a boss; you can just as well have Codex drive Claude. On top of that, three filters keep what actually crosses small:

1. Only agentMessage crosses. The bridge forwards an agent's actual conclusions, not its tool-call noise — command execution, file diffs, and reasoning deltas never reach the other side, nor does its full scrollback.

2. Three-tier marker routing (default). 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 rules live once in the project's AGENTS.md (written by abg init), loaded at startup.

3. The collaboration contract lives once in AGENTS.md, not appended to every message. So each side receives a curated stream of meaningful messages — context grows with the number of real exchanges, not the other agent's raw activity. A full mode is available when you do want the unfiltered stream.

abg installed but won't run — what's wrong?

You're almost certainly missing Bun. AgentBridge's daemon and plugin server run on the Bun runtime; Node.js alone is not enough. Install it with curl -fsSL https://bun.sh/install | bash, then re-run abg claude. This is the most common install failure.

Does AgentBridge support Windows?

Not officially yet. AgentBridge runs on macOS and Linux today. WSL2 may work but is untested and unsupported.

Is it safe? What does --safe do?

By default abg claude launches with --dangerously-skip-permissions and abg codex with --yolo. This is deliberate: an unattended agent pair can't stop to ask you for each permission. Both can then run commands and edit files without prompting, so only do this in a workspace you trust. Add --safe (or set AGENTBRIDGE_SAFE=1) to launch with normal prompts. AgentBridge is a local dev tool, not a hardened boundary between untrusted tools.

How does quota relay actually work?

With the companion agent-quota-guard installed, the daemon polls both agents' 5h and weekly subscription windows. Near a limit the guard lets the current turn finish, stops cleanly at the turn boundary, writes a .agent/checkpoint.md, and drops a pending record. When the window refreshes, the bridge auto-resumes the task in the original interactive TUI: Codex via a queued turn/start, Claude via an acked channel push.

Which agents does it support?

Today the shipping in-session integration connects Claude Code and Codex. Which agent comes next is a public vote. See the adapter roadmap on issue #212 (OpenCode, Gemini CLI, and more are candidates).

How is this different from codex-plugin-cc?

One-way delegation plugins like openai/codex-plugin-cc let a host call Codex and get one answer back: request in, response out, with 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.

Do I need an account or API keys for AgentBridge itself?

No. AgentBridge is a local tool with zero runtime dependencies and no hosted service. You use your existing Claude Code and Codex logins; AgentBridge only relays messages between them on your machine; raw work never leaves the box.

Can I run more than one pair at once?

Yes. One Claude+Codex pair per project directory, with ports allocated per pair in +10 strides from 4500. Target a specific pair with --pair <name> on the pair-aware commands.