{"slug": "a-local-bridge-for-bidirectional-collaboration-between-claude-code-and-codex", "title": "A local bridge for bidirectional collaboration between Claude Code and Codex", "summary": "AgentBridge, an open-source local developer tool by Rayson Meng, enables bidirectional collaboration between Claude Code and Codex in the same working session, allowing cross-review, task splits, and quota relay. The tool, built largely by the two agents collaborating through it, forwards messages between an MCP channel and the Codex app-server protocol, with features like push delivery with fallback, turn coordination, and multiple pair support. It is designed for human-in-the-loop collaboration and is not a hosted service or generic orchestration framework.", "body_md": "**🌐 Website: raysonmeng.github.io/agent-bridge**, with an animated replay of a real session.\n\nDiscussed on\n\n[LINUX DO]— the developer community. / 在[LINUX DO]开发者社区交流。\n\nLocal bridge for bidirectional communication between Claude Code and Codex inside the same working session.\n\n[\n](/raysonmeng/agent-bridge/blob/master/assets/readme-demo.gif)\n\nA real session, replayed — Codex's review is pushed into Claude's live session, no human relay. Full animated demo →\n\nWhat that buys you, concretely:\n\n**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.\n\nThis 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.\n\n⭐ If AgentBridge is useful to you, a star helps other people running two agents find it.\n\n**…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`\n\nlet 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.\n\n**This project is:**\n\n- A local developer tool for connecting Claude Code and Codex in one workflow\n- A bridge that forwards messages between an MCP channel and the Codex app-server protocol\n- An experimental setup for human-in-the-loop collaboration between multiple agents\n\n**This project is not:**\n\n- A hosted service or multi-tenant system\n- A generic orchestration framework for arbitrary agent backends\n- A hardened security boundary between tools you do not trust\n\n**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`\n\nMCP tool, and the bridge injects the reply into the Codex thread as a`turn/start`\n\n.**Push delivery with fallback**— messages arrive as channel notifications; a failed push falls back to an in-memory queue drained by`get_messages`\n\n. Loop prevention via the per-message`source`\n\nfield.**Turn coordination**— a busy-guard rejects replies during an active Codex turn; a per-turn inactivity watchdog stops a lost`turn/completed`\n\nfrom locking injection forever; noisy intermediate events are collapsed so only meaningful`agentMessage`\n\npayloads 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`\n\n/`codex`\n\n/`resume`\n\n/`kill`\n\n/`doctor`\n\n/`budget`\n\nvia`--pair`\n\n.**Resilient lifecycle**— a persistent background daemon survives Claude Code restarts (auto-reconnect with backoff); orphan-process cleanup;`abg doctor`\n\nread-only diagnostics;`abg pairs prune`\n\nreclaims stranded state.**Thread auto-resume**— bare`abg codex`\n\nresumes the pair's last Codex thread;`abg resume`\n\nprints/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](#budget-coordination--auto-resume).\n\nA 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:\n\n**Only** The bridge forwards an agent's actual conclusions, not its tool-call noise —`agentMessage`\n\ncrosses.`commandExecution`\n\n,`fileChange`\n\n, and reasoning deltas never reach the other side, nor does its full scrollback.**Three-tier marker routing**(default`filtered`\n\nmode). Each message is tagged and the daemon routes by tag:`[IMPORTANT]`\n\nforwards immediately,`[STATUS]`\n\nis buffered and batched into one periodic summary (default: 3 updates or 15s),`[FYI]`\n\nis dropped. The marker rules live once in the project's`AGENTS.md`\n\n(written by`abg init`\n\n), loaded at agent startup.**The collaboration contract lives once** in`AGENTS.md`\n\n, not appended to every message (which would pollute every thread and its resume title).\n\nNet 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`\n\n(or the config equivalent) when you *do* want the unfiltered stream.\n\n| Dependency | Version | Install |\n|---|---|---|\n|\n\n`curl -fsSL https://bun.sh/install | bash`\n\n[Claude Code](https://docs.anthropic.com/en/docs/claude-code)`npm install -g @anthropic-ai/claude-code`\n\n[Codex CLI](https://github.com/openai/codex)`npm install -g @openai/codex`\n\nBun is requiredas the runtime for the AgentBridge daemon and plugin server. Node.js alone is not enough. If`abg`\n\ninstalls but won't run, install Bun first (see[Troubleshooting]).\n\nFive steps from nothing to a running pair:\n\n```\n# 1. Install Bun (the runtime; Node alone won't work)\ncurl -fsSL https://bun.sh/install | bash\n\n# 2. Install the CLI. postinstall auto-registers the Claude Code plugin\n#    marketplace AND installs the plugin (best-effort; needs bun + claude present).\nnpm install -g @raysonmeng/agentbridge\n\n# 3. Initialize the project (check deps, install plugin if needed, write .agentbridge/config.json)\nabg init\n\n# 4. Start Claude Code with the AgentBridge channel enabled\nabg claude\n\n# 5. In another terminal, start Codex TUI connected to the same bridge\nabg codex\n```\n\nThat's it: the daemon starts automatically when needed and reconnects if restarted. (`abg`\n\nis a short alias for `agentbridge`\n\n; both are identical.) If the postinstall plugin step was skipped (e.g. Claude Code wasn't installed yet), run `abg init`\n\nto retry it, or see the [manual install fallback](#manual-plugin-install-fallback).\n\nWarning\n\n** 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\n\n**without prompting**. Only do this in a workspace you trust. To launch with normal prompts, add\n\n`--safe`\n\n(`abg claude --safe`\n\n, `abg codex --safe`\n\n) or set `AGENTBRIDGE_SAFE=1`\n\n. The defaults are also auto-suppressed if you pass your own permission flags.With both sides running, give Claude a task that wants a second agent, e.g.:\n\nAsk Claude:\"Propose a task split with Codex for <your task>, then have Codex implement its part while you review.\"\n\nYou 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.\n\nIf the automatic postinstall didn't register the plugin, do it from inside Claude Code:\n\n```\n# 1. Add the AgentBridge marketplace\n/plugin marketplace add raysonmeng/agent-bridge\n\n# 2. Install the plugin\n/plugin install agentbridge@agentbridge\n\n# 3. Reload plugins to activate\n/reload-plugins\n```\n\nTo update later: `/plugin marketplace update agentbridge`\n\nthen `/reload-plugins`\n\n(or enable auto-update under `/plugin`\n\n→ **Marketplaces** → **agentbridge**).\n\nIf you want to modify AgentBridge source code, use the local development setup instead:\n\n```\ngit clone https://github.com/raysonmeng/agent-bridge.git\ncd agent-bridge\nbun install\nbun link\n\nagentbridge dev     # Register local marketplace + install plugin\nagentbridge init    # Check dependencies, generate .agentbridge/config.json\nagentbridge claude  # Start Claude Code with plugin loaded\nagentbridge codex   # (another terminal) Start Codex TUI connected to the bridge\n```\n\nNote:`agentbridge claude`\n\ninjects`--dangerously-load-development-channels plugin:agentbridge@agentbridge`\n\n(a Research Preview workflow). Only enable channels and MCP servers you trust. After changing source, re-run`agentbridge dev`\n\nand restart Claude Code (or`/reload-plugins`\n\n).\n\nAll commands work with both\n\n`agentbridge`\n\nand the short alias`abg`\n\n.\n\n| Command | Description |\n|---|---|\n`abg init` |\nInstall plugin, check dependencies (bun/claude/codex), generate `.agentbridge/config.json` |\n`abg claude [args...]` |\nStart Claude Code with push channel enabled. Runs with (opt out: `--dangerously-skip-permissions` by default`--safe` or `AGENTBRIDGE_SAFE=1` ). Clears any killed sentinel from a previous `kill` . Pass-through args are forwarded to `claude` |\n`abg codex [args...]` |\nStart Codex TUI connected to AgentBridge daemon. Bare (opt out: `abg codex` auto-resumes the pair's last thread; use `abg codex --new` for a fresh thread. TUI launches run with `--yolo` by default`--safe` or `AGENTBRIDGE_SAFE=1` ; non-TUI subcommands like `exec` are never touched). Pass-through args forwarded to `codex` |\n`abg resume [claude|codex]` |\nNo target: print the resume commands for this directory's last Claude session and this pair's current Codex thread. With a target: resume that side directly |\n`abg pairs` |\nList registered pairs; `abg pairs rm <name|id>` removes one; `abg pairs prune` previews reclaimable orphan dirs + stranded registry entries, `--apply` deletes them |\n`abg doctor [--json]` |\nRead-only diagnosis: env, daemon health/readiness, build drift, artifact alignment, TUI attachment, logs |\n`abg budget [--json]` |\nBoth agents' subscription quota snapshot (5h/weekly windows, drift, pause state) |\n`abg logs [--codex] [-f] [-n N]` |\nTail this pair's daemon log (or the Codex wrapper log with `--codex` ); `-f` follows, `-n N` sets the line count (default 100) |\n`abg kill` |\nGracefully stop this pair's daemon and managed Codex TUI, write killed sentinel; `abg kill --all` stops every pair |\n`abg dev` |\n(Dev only) Register local marketplace + force-sync plugin to cache |\n`abg --help` / `abg --version` |\nShow help / version |\n\nThe v3 collaboration layer (shared rooms across machines/agents over a broker: `auth`\n\n, `broker`\n\n, `room`\n\n, `join`\n\n, `publish`\n\n) is in preview on the [ integration/v3-all](https://github.com/raysonmeng/agent-bridge/tree/integration/v3-all) branch and lands here with v3. Spec:\n\n[docs/09-v3协作系统规格.md](/raysonmeng/agent-bridge/blob/master/docs/09-v3%E5%8D%8F%E4%BD%9C%E7%B3%BB%E7%BB%9F%E8%A7%84%E6%A0%BC.md).\n\nThe pair-aware commands (`claude`\n\n, `codex`\n\n, `resume`\n\n, `kill`\n\n, `doctor`\n\n, `budget`\n\n, `logs`\n\n) accept `--pair <name>`\n\nto target a specific pair; one pair per project directory by default, with ports allocated per pair in +10 strides from 4500.\n\nSome flags are automatically injected and cannot be manually specified:\n\n`agentbridge claude`\n\nowns:`--channels`\n\n,`--dangerously-load-development-channels`\n\n`agentbridge codex`\n\nowns:`--remote`\n\n,`--enable tui_app_server`\n\n- Both launchers consume the wrapper flag\n`--safe`\n\n(it is never forwarded): it disables the max-permission defaults for that launch. The defaults are also auto-suppressed when you pass any explicit permission flag yourself (`-a`\n\n/`--ask-for-approval`\n\n/`-s`\n\n/`--sandbox`\n\nfor codex;`--permission-mode`\n\n/`--allow-dangerously-skip-permissions`\n\nfor claude) — injecting`--yolo`\n\nnext to an explicit approval policy is a hard codex CLI conflict.\n\nPassing an owned flag manually is a hard error with guidance to use the native command directly.\n\nNote on flag positioning forfor the bare TUI form, bridge flags are injected at the front; for TUI subcommands that carry per-subcommand args (`agentbridge codex`\n\n:`resume`\n\n,`fork`\n\n), they are injectedafterthe subcommand name; non-TUI subcommands (`exec`\n\n,`mcp`\n\n,`plugin`\n\n, …) are passed through unchanged. See`src/cli/codex.ts buildCodexArgs`\n\n.\n\nAgentBridge is a **two-process** local bridge:\n\n**bridge.ts**— the foreground MCP client started by Claude Code via the AgentBridge plugin. It exits when Claude Code closes.** daemon.ts**— a persistent local background process that owns the Codex app-server proxy and the single source of truth for bridge state. It survives Claude Code restarts;`bridge.ts`\n\nreconnects with exponential backoff.\n\n```\n┌──────────────┐     MCP stdio / plugin     ┌────────────────────┐\n│ Claude Code  │ ──────────────────────────▶ │ bridge.ts          │\n│ Session      │ ◀──────────────────────────  │ foreground client  │\n└──────────────┘                             └─────────┬──────────┘\n                                                       │\n                                                       │ control WS (:4502)\n                                                       ▼\n                                             ┌────────────────────┐\n                                             │ daemon.ts          │\n                                             │ bridge daemon      │\n                                             └─────────┬──────────┘\n                                                       │\n                                     ws://127.0.0.1:4501 proxy\n                                                       │\n                                                       ▼\n                                             ┌────────────────────┐\n                                             │ Codex app-server   │\n                                             └────────────────────┘\n```\n\n| Direction | Path |\n|---|---|\nCodex -> Claude |\n`daemon.ts` captures `agentMessage` -> control WS -> `bridge.ts` -> `notifications/claude/channel` |\nClaude -> Codex |\nClaude calls the `reply` tool -> `bridge.ts` -> control WS -> `daemon.ts` -> `turn/start` injects into the Codex thread |\n\nEach message carries a `source`\n\nfield (`\"claude\"`\n\nor `\"codex\"`\n\n). The bridge never forwards a message back to its origin.\n\nRunning `agentbridge init`\n\ncreates a `.agentbridge/`\n\ndirectory in your project root:\n\n| File | Purpose |\n|---|---|\n`config.json` |\nMachine-readable project config (Codex ports, turn coordination, idle shutdown) |\n\nThe config is loaded by the CLI and daemon at startup. Re-running `init`\n\nis idempotent and will not overwrite existing files.\n\n| Variable | Default | Description |\n|---|---|---|\n`CODEX_WS_PORT` |\n`4500` |\nCodex app-server WebSocket port |\n`CODEX_PROXY_PORT` |\n`4501` |\nBridge proxy port for the Codex TUI |\n`AGENTBRIDGE_CONTROL_PORT` |\n`4502` |\nControl port between bridge.ts and daemon.ts |\n`AGENTBRIDGE_LIVENESS_PROBE_TIMEOUT_MS` |\n`3000` |\nMaximum wait for incumbent Claude pong before evicting on contention (issue #68) |\n`AGENTBRIDGE_TURN_WATCHDOG_MS` |\n`300000` |\nPer-turn inactivity watchdog: force-completes a turn after this many ms of app-server silence so a lost `turn/completed` can't lock injection forever (issue #69) |\n`AGENTBRIDGE_CODEX_TRANSPORT` |\n`auto` |\nHow the daemon reaches the Codex app-server: `auto` (probe `codex app-server --help` , use `ws://` if supported else fall back to a `unix://` socket via a transparent relay), `ws` (force ws), or `unix` (force unix socket + relay). For builds that drop `ws://` listen support (issue #85) |\n`AGENTBRIDGE_STATE_DIR` |\nPlatform default | State directory for pid, status, logs (macOS: `~/Library/Application Support/agentbridge/` , Linux: `$XDG_STATE_HOME/agentbridge/` ) |\n`AGENTBRIDGE_DAEMON_ENTRY` |\n`./daemon.ts` |\nOverride daemon entry point (used by plugin bundles) |\n`NO_UPDATE_NOTIFIER` |\nunset | Set to any value to disable the \"update available\" notice (ecosystem-standard opt-out) |\n`AGENTBRIDGE_NO_UPDATE_NOTIFIER` |\nunset | Namespaced opt-out for the update notice (same effect as `NO_UPDATE_NOTIFIER` ) |\n`AGENTBRIDGE_UPDATE_PROMPT` |\nunset | Set to `0` to disable the interactive update prompt and keep pure notice-only behavior |\n`AGENTBRIDGE_UPDATE_CHECK_INTERVAL_MS` |\n`86400000` |\nHow often `abg claude` /`abg codex` may check npm for a newer version (default once/day). The notice is otherwise printed from cache — zero network on most runs |\n\n`abg claude`\n\nand `abg codex`\n\nprint a one-line notice to stderr when a newer **stable** AgentBridge is published to npm. The check is best-effort: printed from a cached result, the npm check runs at most once per day in the background, and any network/registry failure is silently ignored. On an interactive TTY, a cached update prompts before launch; answering `y`\n\nruns the upgrade, while `N`\n\n(or no answer within 15 seconds) dismisses that version and continues. Disable with `NO_UPDATE_NOTIFIER=1`\n\n, or keep notice-only with `AGENTBRIDGE_UPDATE_PROMPT=0`\n\n.\n\nThe daemon stores runtime state in a platform-aware directory:\n\n| Platform | Default Path |\n|---|---|\n| macOS | `~/Library/Application Support/agentbridge/` |\n| Linux | `$XDG_STATE_HOME/agentbridge/` (fallback: `~/.local/state/agentbridge/` ) |\n\nContents: `daemon.pid`\n\n, `status.json`\n\n, `agentbridge.log`\n\n, `killed`\n\n(sentinel), `startup.lock`\n\nAgentBridge can keep a long task moving across subscription-quota windows instead of letting it die when one agent hits its limit. The capability is driven by the companion tool ** agent-quota-guard** (\n\n[repo](https://github.com/raysonmeng/agent-quota-guard)· v0.2.0, 2026-06-13). Install the guard to enable it.\n\n**Snapshot**— the daemon polls both agents' account-level 5h/weekly quota via the guard's probe;`abg budget [--json]`\n\nprints the live snapshot (both windows, drift, pause state). This works with just the guard's probe.**Slowdown-line (no mid-task cut)**— near the quota hard-line the guard does*not*deny mid-tool-call; it lets the current turn finish, stops cleanly at the turn boundary, writes a`.agent/checkpoint.md`\n\n, and drops a`pending`\n\nrecord 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`\n\ninjection, Claude via a channel push it acks with`ack_resume`\n\n. Per-pending idempotency tombstones ensure a resume is injected at most once, even across daemon restarts.\n\nExperimental / opt-in.This is a companion-guard feature. The Claude-side resume is best-effort (ack + retry + a`SessionStart`\n\nfallback): channel pushes to a fully idle session have known upstream variability, so the bridge only marks a side resumed once it sees a real`ack_resume`\n\n.\n\n- Only forwards\n`agentMessage`\n\nitems, not intermediate`commandExecution`\n\n,`fileChange`\n\n, or similar events - Single Codex thread per pair, no multi-session support within a pair yet\n- Single Claude foreground connection per pair; a new Claude session replaces the previous one\n- Multiple pairs run side-by-side on one machine (one per project directory); Windows is not an officially supported platform yet\n\nFor dormant/disabled bridge states, the Codex `.git`\n\nrestriction, and other gotchas, see ** Troubleshooting**.\n\n**More adapters**— AgentBridge wires Claude Code ↔ Codex today. Candidates for the next agent:** OpenCode, OpenClaw, Hermes Agent, Gemini CLI**. Vote in the[adapter roadmap issue](https://github.com/raysonmeng/agent-bridge/issues/212).** Capability mesh**— beyond messaging: connected agents will publish their commands / skills / MCP tools so a peer can invoke them directly, moving from messaging to capability invocation.**v2 — multi-agent foundation**(partly landed): room-scoped collaboration, stable identity, a formal control protocol, stronger recovery. See[docs/08-v2架构愿景.md](/raysonmeng/agent-bridge/blob/master/docs/08-v2%E6%9E%B6%E6%9E%84%E6%84%BF%E6%99%AF.md).**v3 — cross-network collaboration**(preview on thebranch): shared rooms across machines and agents over a broker. See`integration/v3-all`\n\n[docs/09-v3协作系统规格.md](/raysonmeng/agent-bridge/blob/master/docs/09-v3%E5%8D%8F%E4%BD%9C%E7%B3%BB%E7%BB%9F%E8%A7%84%E6%A0%BC.md).\n\n— disabled-state recovery, the Codex[Troubleshooting](/raysonmeng/agent-bridge/blob/master/docs/TROUBLESHOOTING.md)`.git`\n\nhang, \"installed but won't run\", Bun version requirements— end-to-end usage walkthrough[User manual (EN)](https://github.com/raysonmeng/agent-bridge/blob/integration/v3-all/docs/manual/manual-en.md)— how AgentBridge was built, stage by stage (01–11)[Project growth timeline](/raysonmeng/agent-bridge/blob/master/docs/README.md)\n\nThis project was built collaboratively by **Claude Code** (Anthropic) and **Codex** (OpenAI), communicating through AgentBridge itself, the very tool they were building together. A human developer coordinated the effort: assigning tasks, reviewing progress, and directing the two agents to work in parallel and review each other's output. Two AI agents from different providers, connected in real time, shipping code side by side.\n\nThis is my first open-source project! I'd love to connect with anyone interested in multi-agent collaboration, AI tooling, or just building cool things together. Feel free to reach out:\n\n**Website**:[raysonmeng.pages.dev](https://raysonmeng.pages.dev/)** Twitter/X**:[@raysonmeng](https://x.com/raysonmeng)** Xiaohongshu**:[Profile](https://www.xiaohongshu.com/user/profile/62a3709d0000000021028b7e)** WeChat**: Scan the QR code below to add me", "url": "https://wpnews.pro/news/a-local-bridge-for-bidirectional-collaboration-between-claude-code-and-codex", "canonical_source": "https://github.com/raysonmeng/agent-bridge", "published_at": "2026-08-29 12:05:55+00:00", "updated_at": "2026-08-29 12:18:19.341654+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["AgentBridge", "Rayson Meng", "Claude Code", "Codex", "MCP"], "alternates": {"html": "https://wpnews.pro/news/a-local-bridge-for-bidirectional-collaboration-between-claude-code-and-codex", "markdown": "https://wpnews.pro/news/a-local-bridge-for-bidirectional-collaboration-between-claude-code-and-codex.md", "text": "https://wpnews.pro/news/a-local-bridge-for-bidirectional-collaboration-between-claude-code-and-codex.txt", "jsonld": "https://wpnews.pro/news/a-local-bridge-for-bidirectional-collaboration-between-claude-code-and-codex.jsonld"}}