Skip to main content
Glama

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_*" --> B

Each 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

bridge_inbox

List tasks waiting for you

bridge_show

Read one task in full

bridge_send

Send a new task or message to the other agent (to, subject, body)

bridge_claim

Start working on a task assigned to you

bridge_question

Ask the sender a question about a task

bridge_answer

Answer a question about a task you sent

bridge_review

Ask for a review, or approve / request changes as the sender

bridge_done

Mark a task you own as finished

bridge_ack

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 -> working

Only 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

queued

Stored, not attempted yet

dispatching

A dispatcher is working on the delivery

os_posted / plugin_delivered

A notification or host card was accepted; the target hasn't confirmed yet

viewed

The target opened the delivery

launch_started

A wake process started; this is not a confirmation

agent_acknowledged

The target checked its inbox

claimed

The assignee claimed the task

retry_wait

A failed attempt is scheduled to retry

failed

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 claude command working in a terminal (check with claude --version).

  • Codex (the desktop app or the CLI). Open it at least once, so that the ~/.codex folder 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-bridge on 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 -Auto

macOS / Linux

git clone https://github.com/RajeshMadanu/claude-bridge.git
cd claude-bridge
./install.sh --auto

What the installer does

  1. Installs the agent-bridge Python package for your user from the bundled offline wheel (pip install --user, no internet needed).

  2. Copies a private runtime to ~/.agent-bridge/skill/runtime and adds a bridge command to ~/.local/bin (it adds that folder to your PATH).

  3. For Codex, adds an [mcp_servers.agent_bridge] block to ~/.codex/config.toml.

  4. For Claude Code, adds a SessionStart hook to ~/.claude/settings.json, then registers the agent_bridge MCP server for your user with claude mcp add (via scripts/connect_claude_mcp.py).

  5. 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

integrations/instructions/CLAUDE.md

~/.claude/CLAUDE.md

Codex

integrations/instructions/AGENTS.md

~/.codex/AGENTS.md

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_bridge should be listed as connected. From a terminal, claude mcp get agent_bridge shows the same.

  • Codex: ~/.codex/config.toml should 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 --strict and bridge 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 tui

Maintenance:

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 uninstall

For 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 bridge_* tools

Run python scripts/connect_claude_mcp.py from this folder (use python3 on macOS/Linux), then restart Claude Code. To do it by hand, run python scripts/connect_claude_mcp.py --print and paste the command it prints.

Codex has no bridge_* tools

Make sure Codex was opened once, then run .\install.ps1 -Agent codex (or ./install.sh --agent codex) and restart Codex.

requested host application is not detected

Open that app once, or install with -Agent claude / -Agent codex to set it up explicitly.

bridge is not recognized

Open a new terminal (the PATH change only applies to new ones), or run ~/.local/bin/bridge.

A task shows sender unknown

It was sent from the terminal without --as. Use the MCP tools or pass --as claude / --as codex.

Something looks broken

Run bridge doctor --strict and bridge setup --repair. There is no daemon to restart.

Every config change has a backup in ~/.agent-bridge/backups/<app>/.


Uninstall

.\install.ps1 -Uninstall              # Windows
./install.sh --uninstall              # macOS / Linux

This 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.cmd and multi-line text: cmd.exe stops reading arguments at the first line break, so a multi-line --body or --result passed through bridge.cmd is cut short. The MCP tools are not affected. This is tracked by the expected-failure tests in tests/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 tools
bridge_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

    D1.9/5.0

    Scored across 22 tools

    Disambiguation2/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      16
      209 PyPI
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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