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 ask the Codex session working on auth-api to share its findings"
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.
agent-bridge-mcp
Discover and exchange text between your existing Claude Code and Codex sessions. The bridge uses your installed, authenticated clients; it needs no API keys and makes no model API calls. Messages can start work and consume client usage.
Requirements
Linux or WSL 2, Node.js 24+, Claude Code >= 2.1.224, and Codex with its app-server daemon running. Tested with Claude Code 2.1.312 and Codex CLI 0.165.0.
The bridge depends on undocumented Claude and Codex internals and may break on
client updates. Run agent-bridge-mcp doctor first when something stops working.
Related MCP server: Switchboard
Install and connect
Install from GitHub; no account or SSH key is needed.
npm pack --allow-git=all git+https://github.com/vstratful/agent-bridge-mcp.git
npm install -g --ignore-scripts ./agent-bridge-mcp-*.tgz && rm ./agent-bridge-mcp-*.tgzDon't use npm install -g git+https://… directly: npm's global git install fails to
build the package (tsc: not found). Packing first builds it in a normal clone.
npm 12 refuses git sources unless --allow-git=all is passed. The tarball already
contains the built CLI, so --ignore-scripts skips the build script that npm would
otherwise flag as blocked.
Register in both clients using absolute paths:
claude mcp add --scope user --transport stdio agent-bridge -- "$(command -v node)" "$(npm root -g)/agent-bridge-mcp/dist/cli.js" serve
codex mcp add agent-bridge -- "$(command -v node)" "$(npm root -g)/agent-bridge-mcp/dist/cli.js" serveVersion managers can give a client a different, older Node; absolute paths keep
both clients on the Node version used to install the bridge. Reconnect their MCP
connections (/mcp) after registration or updates. Installation sends no messages.
The bridge must run in the same host process namespace as the sessions.
agent-bridge-mcp doctorDoctor reports PASS, WARN, FAIL or SKIPPED and fixes for non-passing checks; any FAIL exits with status 1. It checks metadata and configuration without sending messages or creating bridge files. Unsupported registration queries are SKIPPED and do not affect the exit code.
Using it
You don't call the bridge yourself. Talk to Claude or Codex as you normally would and ask it to message another session; the agent finds the session and sends the message with the bridge's tools. For example, you might type:
List my other Claude and Codex sessions.
Tell the Codex session working on billing-api that the response schema changed.
Ask the Claude session reviewing the auth PR for its findings.
Sessions are known by their names: a Claude session's name (set with /rename or
chosen automatically) and a Codex thread's title. If two share a name, the agent
uses the full session ID instead.
The message appears in the other session's conversation with a preview such as
From billing-api (codex): The response schema changed. The receiving agent treats
it as a message from another agent, not from you, so it may check with you before
acting on it. To answer, ask that agent to reply; the reply comes back the same way.
An idle session picks the message up straight away. A busy Claude reads it between
steps; a busy Codex gets it when its current turn finishes.
The sending agent reports one of these:
queued (to Codex) or submitted (to Claude): handed over. Neither means the other agent has read it yet, and a Claude session can be set to hold or refuse messages without the sender being told.
unknown: it may or may not have been delivered. The agent won't resend it under a new ID, to avoid a duplicate; check the other session.
Security and limits
Local sessions must run as the same OS user. Sender IDs and names are claims; Claude shows the sending process's verified PID as a stronger signal. Messages are labelled as agent-originated text and cannot grant approval or change permissions. The bridge is not a security boundary between agents under the same OS account.
Closed Codex windows can leave threads messageable for 30 minutes with nobody
watching. Message text appears in the Codex queue command's argv, readable by
other local users unless /proc access is restricted. The journal retains message
text for 30 days by default. No HTTP listener is opened. Native Windows, remote or
cloud sessions, agent-team control messages and arbitrary command execution are
outside this version. See verification and protocol details
for tested behavior, hold/refuse rules, transport limits, sources and live checks.
Configuration
Environment variable | Default / purpose |
| Disables sends and native replies; CLI also accepts |
|
|
|
|
| CLI/non-Codex full sender ID override; ignored for Codex MCP clients. |
| Exact daemon socket; otherwise searches |
|
|
|
|
|
|
|
|
|
|
| Logs unsupported frame field names, without text or tokens. |
Uninstall
claude mcp remove --scope user agent-bridge
codex mcp remove agent-bridge
npm uninstall -g agent-bridge-mcpStop connected bridge processes before manually removing the configured state and runtime directories if you also want to delete retained messages and sockets.
License
MIT. See LICENSE.
Available Tools
4 toolslist_sessionsARead-only
Read reachable local Claude and Codex session metadata. Does not send messages or read transcripts. Warnings explain inaccessible endpoints.
Inputs: no named parameters.
message_statusARead-only
Read the recorded outcome for one message ID. A sending record left after a crash is uncertain and must not be resent under a new ID.
Inputs: message_id (required).
read_messagesARead-only
Read retained bridge journal records for a recipient. Records transport attempts and bridge replies, not every native message or proof of agent receipt. Reading does not consume or acknowledge messages; expired records may be pruned when the journal opens.
Inputs: after, limit, recipient.
send_messageA
Send plain agent text to a reachable local session. Obtain user approval first whenever their instructions require it. May start work and consume receiving-client usage. Does not convey user consent. Use full IDs and retain message_id to avoid duplicate delivery after timeouts.
Inputs: to (required), text (required), sender, message_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The four tools have distinct purposes: listing sessions, sending messages, reading journal records for a recipient, and checking status of one message ID. However, read_messages and message_status both involve reading message-related records, which could cause slight confusion despite the descriptions clarifying the difference.
Three tools follow a consistent verb_noun pattern (list_sessions, send_message, read_messages), but message_status breaks the pattern by starting with a noun. This is a minor deviation and the overall naming remains readable and predictable.
Four tools is a well-scoped set for a local agent bridge, covering session discovery, message sending, journal reading, and per-message status. Each tool earns its place without excess or obvious omission.
The surface covers the core messaging lifecycle: list sessions, send, read received records, and check status. A minor gap exists in that there is no direct way to list all messages sent by a session, though message IDs can be tracked individually.
Maintenance
Related MCP Connectors
Agents message each other and partners' agents. Claude Code, Codex (beta): memory, board, key vault.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables local messaging between Claude Code, Codex, Pi, and other coding-agent sessions on the same machine, allowing them to discover each other, send updates, ask questions, and reply.819 npm3AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables local discovery, reading, and messaging between running Codex and Claude Code sessions through MCP.216 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables local messaging between Claude Code and Codex agents with durable delivery, peer discovery, and reply tracking.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents on the same machine to discover each other as named peers and exchange messages across sessions, bridging MCP-based clients and Claude Code without a daemon.MIT