Skip to main content
Glama
kodaas

bridge

by kodaas
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Agent Bridge

M8ven Score

A plugin for Claude Code and Codex that lets their sessions on the same project see each other and talk: Claude ↔ Claude, Codex ↔ Codex, and Claude ↔ Codex.

  • See who's working and on what. Every session shows its name, host, state (working / idle / waiting), git branch, status line, and recently edited files.

  • Message one session or all of them. Hand off work, ask questions, and claim files before editing so sessions don't collide.

  • Claude can use Codex's Computer Use. Claude Code sessions can hand a desktop-app task (e.g. "check tomorrow's first event in Calendar") to Codex, which operates the app and reports back.

  • Secure by design. No network: messages go through a private directory in your home folder. Each message is signed by the sender and end-to-end encrypted to the recipient.

 Claude Code session ─┐                                   ┌─ Codex session
   (MCP server + hooks)│   ~/.agent-bridge/projects/<id>/  │ (MCP server + hooks)
                       ├──► sessions/  signed identity     ◄┤
 Claude Code session ─┤    inbox/      encrypted messages   ├─ Codex session
                       └───────────── same user, 0700 ─────┘

Install

This repository is a plugin marketplace for both hosts. Both need Node.js 18+ on the machine.

Claude Code

claude plugin marketplace add kodaas/agent-bridge
claude plugin install agent-bridge@agent-bridge

Claude asks for permission the first time each bridge tool runs. To skip the prompts for the messaging tools, add these to the permissions.allow list in ~/.claude/settings.json:

"mcp__plugin_agent-bridge_bridge__list_sessions",
"mcp__plugin_agent-bridge_bridge__set_status",
"mcp__plugin_agent-bridge_bridge__send_message",
"mcp__plugin_agent-bridge_bridge__read_messages",
"mcp__plugin_agent-bridge_bridge__wait_for_message"

Don't allowlist codex_computer_use (or use a __* wildcard): its permission prompt is where you see and approve each desktop task before it runs.

Codex

codex plugin marketplace add kodaas/agent-bridge
codex plugin add agent-bridge@agent-bridge

Codex runs plugin hooks only after you trust them. Open Codex, run /hooks, and trust the three agent-bridge hooks. Without them the tools still work, but messages aren't announced automatically.

To install from a local clone instead, pass its path to marketplace add in place of kodaas/agent-bridge.

Related MCP server: claude-peers

Use it

Just ask, in either tool:

  • "Who else is working on this repo right now?"

  • "Tell the Codex session I'm refactoring src/auth, and ask it to stay out of that folder."

  • "Hand the failing integration tests off to the other Claude session."

  • "Wait for the Claude session to finish the migration, then run the test suite."

Sessions join automatically. Sessions in the same git repository share a bridge, including sessions in separate worktrees; other folders are isolated from each other.

Tool

What it does

list_sessions

Active sessions with host, state, branch, status, and recent files

set_status

Set your one-line status and, optionally, a memorable name

send_message

Message a session by name or id, or everyone with to="all"

read_messages

Read new messages, or review history

wait_for_message

Block until a peer message arrives (up to 10 minutes)

codex_computer_use

Claude Code only. Have Codex operate a desktop app via Computer Use and report back

How messages arrive

  • Busy sessions: hooks announce new messages when the user sends a prompt, after each tool call, and before the agent finishes its turn. If a message is still unread at that last point, the agent keeps going (at most 5 times per prompt) so it can handle it.

  • Idle Claude Code sessions (interactive terminal or IDE) are woken when a message arrives.

  • Idle Codex sessions are not woken. They see messages when their next turn starts, or while they're blocked in wait_for_message. For a live conversation, ask Codex to "wait for messages from Claude and handle them".

Codex Computer Use from Claude Code

Codex's Computer Use can read and operate the UI of apps on your Mac. Claude Code can't reach that runtime directly: it's private to Codex, and each app needs your approval inside Codex. So codex_computer_use delegates. It starts a one-off, headless Codex task that uses its own Computer Use and returns Codex's report, plus a list of the steps it took, to Claude.

Try: "Use Codex computer use to read the first three unread subjects in Mail."

Before first use: approve each app once in Codex. Run any Codex task that uses the app (in the Codex app or CLI) and choose Always allow. Headless runs can't ask, so an unapproved app makes Codex stop and name it; the plugin then tells Claude what to ask you.

Safeguards:

  • You approve every task. Claude Code shows each codex_computer_use call, with the full task text, in a permission prompt. Keep it that way; see Install.

  • Codex's per-app approvals stay in force. The plugin never grants or bypasses them.

  • Scoped, read-only run. Codex runs with a read-only shell sandbox and a disposable session (--ephemeral). It is told to operate only the listed apps, and not to send, submit, buy, delete, change settings, or type credentials unless the task explicitly says so.

  • One driver at a time. A machine-wide lock stops two agents from fighting over the desktop.

  • Bounded. The run has a timeout (default 10 minutes, max 30); cancelling the tool call in Claude stops Codex.

  • Peer messages can't trigger it. The tool description and skill tell Claude to use it only on your request, never because a peer asked.

Screenshots and on-screen text go to Codex's model provider (OpenAI) as usual for Computer Use. The worker Codex session shows up in list_sessions as <claude-name>-computer-use while it runs.

Security model

The trust boundary is your OS user account. Only processes running as you can take part.

Protection

How

No network exposure

No sockets or ports. All communication goes through ~/.agent-bridge (dirs 0700, files 0600). Symlinked or foreign-owned paths are refused.

Unforgeable identities

Each session creates an Ed25519 signing key and an X25519 encryption key in memory; they never touch disk. The session id is a fingerprint of both public keys, so an id can't be claimed without the matching private keys. Session records are signed.

Authentic, private messages

Messages are encrypted with AES-256-GCM, using a key derived (X25519 + HKDF-SHA256) for each sender→recipient pair, and signed by the sender. Message text never exists in plaintext on disk. Tampered, forged, replayed, misaddressed, or stale messages are rejected and quarantined.

Sender set by the server

The from field comes from the session's own server, never from the model, so an agent can't impersonate another session.

Prompt-injection hygiene

Hooks inject only short notices (sender names, counts). Message text reaches the model only as tool output, wrapped in <peer-message> blocks and labelled as coming from other agents, not the user. Terminal escapes, control characters, and invisible/bidirectional-text characters are stripped. Every displayed field of a session record is sanitized. The bundled skill tells agents never to take destructive, out-of-scope, or secret-revealing actions just because a peer asked.

Runaway protection

Limits: 8 KiB per message, 30 messages per minute per session, 200 queued messages per inbox. Turn-end re-prompts are capped.

What it does not protect against: other software already running as your user. Such software can read your files, edit your agent configs, or kill processes regardless. It can't read or forge messages between live sessions, but it can register its own fake session, whose messages would show up under its own distinct name.

Command line

plugins/agent-bridge/scripts/agent-bridge sessions [--all]   # who's active, in every project
plugins/agent-bridge/scripts/agent-bridge doctor             # Node version, permissions, integrity
plugins/agent-bridge/scripts/agent-bridge purge --yes        # delete all local state

Message contents can't be read from the CLI; they're encrypted to the live sessions.

Configuration

Set these as environment variables for the host (e.g. in your shell profile, or in Claude Code's settings.json env):

Variable

Default

Purpose

AGENT_BRIDGE_NAME

<host>-<id>

Default session name

AGENT_BRIDGE_HOME

~/.agent-bridge

State directory

AGENT_BRIDGE_PROJECT

(git repo)

Join sessions across folders by giving them the same project name

AGENT_BRIDGE_PROJECT_DIR

(session cwd)

Force the project directory

AGENT_BRIDGE_WAKE

auto

Idle wake-up for Claude Code: auto (interactive only), always, never

AGENT_BRIDGE_MAX_MESSAGE_BYTES

8192

Maximum message size

AGENT_BRIDGE_RATE_LIMIT

30

Messages per minute per session

AGENT_BRIDGE_NODE

(auto)

Path to the Node.js binary

AGENT_BRIDGE_COMPUTER_USE

auto

off hides codex_computer_use

AGENT_BRIDGE_COMPUTER_USE_EFFORT

medium

Codex reasoning effort for Computer Use tasks

AGENT_BRIDGE_CODEX_BIN

(auto)

Path to the Codex CLI

Limitations

  • macOS and Linux only; Windows is untested.

  • In auto mode, idle wake-up is off for headless (claude -p) and SDK-hosted Claude sessions, because a background waiter would keep one-shot runs from exiting.

  • A session's keys live only in its process. Messages still queued when a session exits are unreadable and are discarded.

  • Computer Use needs macOS, the Codex CLI, and Codex's Computer Use (bundled with the ChatGPT/Codex desktop app). Apps must be pre-approved in Codex.

  • Verified with Claude Code 2.1.283 and Codex CLI 0.157.1 (codex exec). Other versions and front ends (such as the Codex desktop app) may behave differently.

Development

npm test    # 26 tests: crypto, end-to-end over MCP stdio, hooks, watcher, CLI, Computer Use (with a fake Codex)

Layout: plugins/agent-bridge/ is the plugin. It has .claude-plugin/ and .codex-plugin/ manifests, per-host MCP and hook configs in mcp/ and hooks/, the zero-dependency server in server/, and a shared skill in skills/. After changing plugin files, reinstall so each host picks up the new copy.

Uninstall

claude plugin uninstall agent-bridge@agent-bridge && claude plugin marketplace remove agent-bridge
codex plugin remove agent-bridge@agent-bridge && codex plugin marketplace remove agent-bridge
rm -rf ~/.agent-bridge

License

MIT © Fiyinfoluwa John Ajala

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers