agent_bridge
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agent_bridge send Codex a task to review my latest pull request"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Claude Bridge
Connect Claude Code and Codex on one computer so they can send each other tasks, ask questions, review each other's work, and reply, both ways.
Claude Bridge is a ready-to-use packaging of Agent Bridge by 圆规 (Yuangui) (@xyva-yuangui), set up and tested for a two-way Claude Code ⇄ Codex connection. It is released under the same Apache-2.0 license. See NOTICE for the original copyright and the list of changes made in this repository.
Everything stays on your machine. Tasks are stored in a local SQLite database
under ~/.agent-bridge. There is no server, no account, no cloud sync, no
network listener and no telemetry, and it needs nothing but Python's standard
library.
License · Notice · Security · Contributing · Architecture · Windows install details · macOS install details · Migrating from v1 · 简体中文
How it works
flowchart LR
C["Claude Code<br/>(identity: claude)"] <-- "MCP tools<br/>bridge_*" --> B[("~/.agent-bridge<br/>local task board")]
X["Codex<br/>(identity: codex)"] <-- "MCP tools<br/>bridge_*" --> BEach app starts its own small MCP server (agent_bridge). The server is
locked to that app's identity, so Claude Code always acts as claude and
Codex always acts as codex; neither can pretend to be the other. Both
servers read and write the same local task board.
Each app gets these tools:
Tool | What it does |
| List tasks waiting for you |
| Read one task in full |
| Send a new task or message to the other agent ( |
| Start working on a task assigned to you |
| Ask the sender a question about a task |
| Answer a question about a task you sent |
| Ask for a review, or approve / request changes as the sender |
| Mark a task you own as finished |
| Confirm a delivery card (used by the host integration) |
Task lifecycle:
send -> pending -> claim -> working -> done -> completed
-> question -> input_required -> answer -> pending
working -> review -> review_requested -> approve -> completed
-> changes -> changes_requested -> claim -> workingOnly the assignee can claim, ask, request review or finish a task. Only the sender can answer or give a review verdict.
Delivery status
Every delivery attempt records one status, so "sent" is never confused with "received":
Status | Meaning |
| Stored, not attempted yet |
| A dispatcher is working on the delivery |
| A notification or host card was accepted; the target hasn't confirmed yet |
| The target opened the delivery |
| A wake process started; this is not a confirmation |
| The target checked its inbox |
| The assignee claimed the task |
| A failed attempt is scheduled to retry |
| The delivery attempt failed (the task itself is still stored) |
Related MCP server: cmdr
Requirements
Python 3.9 or newer (tested on 3.9–3.13). On Windows, install it from python.org and tick "Add python.exe to PATH".
Claude Code, with the
claudecommand working in a terminal (check withclaude --version).Codex (the desktop app or the CLI). Open it at least once, so that the
~/.codexfolder exists.Windows 10/11 with PowerShell 5.1+, or macOS/Linux with Bash.
Git, to download this repository (or download the ZIP from GitHub).
A local disk. Don't put
~/.agent-bridgeon a network share or a cloud-sync folder.
No pip install of anything else is needed. The installer ships an offline
wheel (bootstrap/) and uses only the standard library.
Install
Close Claude Code and Codex first.
Windows (PowerShell)
git clone https://github.com/RajeshMadanu/claude-bridge.git
cd claude-bridge
powershell -ExecutionPolicy Bypass -File .\install.ps1 -AutomacOS / Linux
git clone https://github.com/RajeshMadanu/claude-bridge.git
cd claude-bridge
./install.sh --autoWhat the installer does
Installs the
agent-bridgePython package for your user from the bundled offline wheel (pip install --user, no internet needed).Copies a private runtime to
~/.agent-bridge/skill/runtimeand adds abridgecommand to~/.local/bin(it adds that folder to your PATH).For Codex, adds an
[mcp_servers.agent_bridge]block to~/.codex/config.toml.For Claude Code, adds a SessionStart hook to
~/.claude/settings.json, then registers theagent_bridgeMCP server for your user withclaude mcp add(viascripts/connect_claude_mcp.py).Backs up every config file it changes to
~/.agent-bridge/backups/, and records what it owns, so uninstall removes only its own changes.
-Auto / --auto sets up every supported app it finds. To set up only one,
use -Agent claude or -Agent codex (--agent claude / --agent codex on
macOS/Linux). To pick a specific Python, add -Python C:\path\to\python.exe
(--python /path/to/python3).
Finish the setup (2 minutes)
1. Tell each agent how to use the bridge
Copy the ready-made instructions into each app's global instruction file:
App | Copy this file's section | Into |
Claude Code |
| |
Codex |
|
They tell each agent to check its inbox every turn, use only the MCP tools
(never a terminal, so your keyboard and screen stay free), and reply with
bridge_send. A reply written only in a task's done-result is not shown by
bridge_show or bridge_inbox, so the other side might never read it.
2. Restart both apps
Claude Code and Codex load MCP servers only at startup.
3. Check the connection
Claude Code: run
/mcp.agent_bridgeshould be listed as connected. From a terminal,claude mcp get agent_bridgeshows the same.Codex:
~/.codex/config.tomlshould contain the[mcp_servers.agent_bridge]block. Ask Codex to "call bridge_inbox"; it should answer with an (empty) task list.Bridge health, in a new terminal:
bridge doctor --strictandbridge setup status.
4. Send a test message
In Claude Code, say:
Use bridge_send to send codex a task with subject "ping" and body "reply with pong".
Then in Codex, say "check the bridge". Codex should claim the task, reply to
claude with bridge_send, and mark the task done. Back in Claude Code, say
"check the bridge" to see the reply. If both directions work, you're done.
Everyday use
Just talk to either agent in plain language:
"Ask Codex to review the diff in this repo and send back its findings."
"Send Claude the failing test output and ask it to fix the bug."
"Check the bridge and handle anything that's waiting."
The agents take care of claiming, replying and closing tasks, following the instructions from step 1.
Both agents only see new tasks when they check their inbox. They don't run in the background on their own. The instructions make them check at the start of every turn, so when you're waiting on a reply, send the other app any short message (for example "check the bridge").
Terminal commands (optional)
The bridge command works in any new terminal after installing. Use
--as <name> to choose the identity:
bridge --as claude inbox
bridge --as claude send --to codex --subject "Review the patch" --body "Run the tests"
bridge --as codex claim <task-id>
bridge --as codex done <task-id> --result "Fixed and tested"
bridge board
bridge activity
bridge tuiMaintenance:
bridge --version
bridge doctor --strict
bridge setup status
bridge setup --repair
bridge setup --dry-run
bridge export backup.json
bridge migrate path/to/v1-board.json
bridge uninstallFor agent-to-agent messages, prefer the MCP tools. On Windows, bridge.cmd
cuts multi-line --body / --result text at the first line break (see
Known issues).
Troubleshooting
Problem | Fix |
Claude Code has no | Run |
Codex has no | Make sure Codex was opened once, then run |
| Open that app once, or install with |
| Open a new terminal (the PATH change only applies to new ones), or run |
A task shows sender | It was sent from the terminal without |
Something looks broken | Run |
Every config change has a backup in ~/.agent-bridge/backups/<app>/.
Uninstall
.\install.ps1 -Uninstall # Windows
./install.sh --uninstall # macOS / LinuxThis removes the Claude Code MCP registration, the hook, the Codex config
block, the launcher and the PATH entry. Your task history in ~/.agent-bridge
is kept. Add -PurgeData / --purge-data to delete it as well (the exact
folder is printed first).
bridge uninstall on its own removes everything except the Claude Code MCP
registration. Remove that with python scripts/connect_claude_mcp.py --remove
or claude mcp remove agent_bridge -s user.
Known issues
Windows
bridge.cmdand multi-line text:cmd.exestops reading arguments at the first line break, so a multi-line--bodyor--resultpassed throughbridge.cmdis cut short. The MCP tools are not affected. This is tracked by the expected-failure tests intests/platform/test_windows_launcher_args.py.Notifications: the Windows toast helper is x86-64 only. Clicking a toast's View button deliberately opens the task in Windows Terminal. macOS notification permission, signing and notarization are real-machine checks that CI cannot prove.
Other agents
The engine also supports Reasonix and ZCode; -Auto configures them
when it finds them. This repository is documented and tested for the Claude
Code ⇄ Codex pair. See the original project for the others.
Development
python -m unittest discover -s tests -t . -v
python -m compileall -q src scripts tests
python scripts/bootstrap_wheel.py --check # the bundled wheel matches src/
python scripts/bootstrap_wheel.py --write # rebuild it after changing src/ (needs setuptools)Run the tests on a machine (or in CI) where Agent Bridge is not already installed for your user. Several installer tests refuse to overwrite a real installation's Windows environment values, and that shows up as failures. GitHub Actions runs the full suite on Windows, macOS and Linux for Python 3.9–3.13 on every push.
See CONTRIBUTING.md and the release checklist.
Available Tools
22 toolsbridge_activityD
Execute bridge activity through the v2 service.
Inputs: since, project.
bridge_agentsD
Execute bridge agents through the v2 service.
Inputs: no named parameters.
bridge_answerD
Execute bridge answer through the v2 service.
Inputs: body (required), task_id (required), no_wake.
bridge_boardD
Execute bridge board through the v2 service.
Inputs: project.
bridge_claimD
Execute bridge claim through the v2 service.
Inputs: task_id (required), body, no_wake.
bridge_cleanD
Execute bridge clean through the v2 service.
Inputs: all, days, status, dry_run, +1 more.
bridge_contextD
Execute bridge context through the v2 service.
Inputs: add, show, project.
bridge_doctorD
Execute bridge doctor through the v2 service.
Inputs: strict.
bridge_doneD
Execute bridge done through the v2 service.
Inputs: task_id (required), files, result, no_wake.
bridge_exportD
Execute bridge export through the v2 service.
Inputs: destination (required).
bridge_inboxD
Execute bridge inbox through the v2 service.
Inputs: limit, cursor.
bridge_logD
Execute bridge log through the v2 service.
Inputs: what (required), project.
bridge_migrateD
Execute bridge migrate through the v2 service.
Inputs: source (required).
bridge_projectD
Execute bridge project through the v2 service.
Inputs: action (required), goal, name, workspace.
bridge_questionD
Execute bridge question through the v2 service.
Inputs: body (required), task_id (required), no_wake.
bridge_reviewD
Execute bridge review through the v2 service.
Inputs: task_id (required), body, no_wake, verdict.
bridge_sendD
Execute bridge send through the v2 service.
Inputs: to (required), subject (required), body, no_wake, +1 more.
bridge_showD
Execute bridge show through the v2 service.
Inputs: task_id (required).
bridge_statusD
Execute bridge status through the v2 service.
Inputs: oneliner.
bridge_wakeD
Execute bridge wake through the v2 service.
Inputs: agent (required), project.
bridge_whoamiC
Execute bridge whoami through the v2 service.
Inputs: no named parameters.
bridge_who_coordinatesD
Execute bridge who-coordinates through the v2 service.
Inputs: project.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Every tool carries the identical boilerplate description ('Execute bridge_<name> through the v2 service'), so descriptions provide zero help in telling tools apart. Names alone leave several clusters ambiguous: bridge_show/status/board/context/inbox, bridge_export/log/activity, and bridge_clean/doctor/migrate could easily be confused.
All 22 tools use a uniform bridge_<snake_case> prefix, which is highly predictable. The only minor deviation is mixing nouns (inbox, board, context, agents) with verbs (send, claim, done) and the multi-word bridge_who_coordinates, but the pattern remains readable.
At 22 tools the surface is heavy for what appears to be an agent-coordination bridge; each tool may earn its place, but the sheer number plus identical descriptions makes the set feel bloated and hard to navigate.
The names suggest a fairly full coordination lifecycle (send, inbox, claim, done, question/answer, review, board, activity, log, whoami, migrate, doctor), but with no meaningful descriptions it is impossible to confirm coverage. Obvious update/edit or delete/close operations for messages and tasks are not clearly represented.
Related MCP Connectors
A task list shared by you and your coding agents (Claude Code, Cursor, Codex and any MCP client). Agents plan each task into steps, report live progress to a board, and block on questions you answer from your phone.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Project board for ChatGPT, Claude and coding agents, with scoped MCP access to projects and tasks.
Related MCP Servers
- AlicenseAqualityDmaintenanceOne local MCP server that lets Codex and Claude Code coordinate through a shared task board and message inbox.61MIT
- AlicenseNot gradedqualityBmaintenanceEnables multiple coding agent sessions to form local squads where a commander dispatches tasks and executors report progress, ask questions, and receive correlated answers through MCP tools backed by a persistent SQLite message queue.66 npm1MIT
- AlicenseAqualityBmaintenanceEnables multiple AI coding tools to collaboratively review code by sharing a SQLite-backed board, allowing them to create threads, post and reply to comments, list threads, and update statuses through MCP.16209 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceEnables running both Claude Code and Codex locally with a shared task board, session resume, cross-agent handoff, and an MCP bridge for inter-client messaging and task/context inspection.MIT