agent-bridge MCP server

agent-bridge

Let your AI agents on different machines talk to each other.

agent-bridge connects running AI agent harness sessions across your own computers using SSH and local inboxes. Send a task to the agent already sitting on another laptop, ask your always-on desktop to run a diagnostic, or let different harnesses coordinate without copy-pasting between chats.

Website | GitHub

---

Why use it?

• Agent-to-agent messages — push work to a live agent on another machine and get a reply in context.
• No cloud relay — peer-to-peer over SSH; config, keys, inboxes, and logs live on your machines.
• Works across harnesses — Claude Code and OpenClaw are tested end-to-end, with the same bridge tools shared through MCP.
• Remote diagnostics when needed — run plain shell commands on a paired machine for status checks, logs, tests, and one-off troubleshooting.
• Explicit routing — target Claude Code personas, OpenClaw accounts, or other named sessions directly instead of relying on fuzzy defaults.
• Shared context — a fleet-wide learnings store every agent on every machine can search and contribute to, replicated peer-to-peer over the same SSH transport.

What works today

• Claude Code: tested end-to-end with a unified MCP/channel plugin.
• OpenClaw: tested end-to-end with a native channel plugin plus the shared MCP tools.
• Codex (4.10.0+): first-class both ways — bound tasks receive pushed turns via the background codex-channel service (the task itself never polls; the service scans the inbox and wakes the exact persisted thread through the App Server), and any Codex task sends via the bridge MCP tools or agent-bridge codex send.
• Other MCP hosts (Gemini CLI, Aider): scaffolded for manual receive/polling flows; empirical reports and PRs are welcome.

---

Quick start

Paste this into your Claude Code or OpenClaw session on each computer you want to bridge:

Read the README at https://github.com/EthanSK/agent-bridge and follow the setup instructions
for this computer. Install agent-bridge, run the setup command, and install the appropriate
channel plugin (Claude Code's `mcp-server/` plugin OR OpenClaw's `openclaw-channel/`,
matching whichever harness you're running). Do everything automatically — don't ask me
questions.

Prereqs (once per machine):

• macOS: System Settings > General > Sharing > toggle Remote Login ON > click (i) > set "Allow access for" to All users. Optionally toggle "Allow full disk access for remote users".
• Linux: sudo systemctl enable --now sshd
• Windows 10/11: OpenSSH Server is an optional feature, not on by default. See the Windows setup section below for the consolidated install + firewall + admin-key script.

Then photograph the pairing screen on one machine and send it to the Claude Code or OpenClaw session on the other. That's the pair step; the agents handle the rest. Either harness can pair with either harness — Claude Code↔OpenClaw, OpenClaw↔OpenClaw, etc.

---

Setup notes

agent-bridge is designed for people to use, but first-time setup still depends on SSH, local agent plugins, and the agent harness you run. If something does not work first try:

• Ask your local AI agent (Claude Code, OpenClaw, etc.) to inspect the setup and logs for your machine. The bridge writes structured NDJSON logs at ~/.agent-bridge/logs/agent-bridge.log, and event names are documented in docs/operations.md.
• Open an issue at https://github.com/EthanSK/agent-bridge/issues with the failure mode and your environment details.
• PRs are welcome — especially small fixes for cross-platform paths, alternate install locations, and harness-specific quirks.

---

For agents setting this up

If you are an AI agent onboarding agent-bridge onto a new machine, read the setup docs before sending your first bridge message. The three most important docs are:

• docs/named-target-routing.md — when the user names a specific target alias, match that alias literally.
• docs/relay-to-user.md — inbound bridge messages should be relayed to the user with a short summary plus source/destination endpoint versions.
• docs/operations.md — stale runtime recovery, plugin reloads, and the practical checks for "I rebuilt but nothing changed."

Other docs in docs/ cover auto-update, channel-plugin history, lifecycle notes, and investigation reports.

---

What is agent-bridge?

agent-bridge lets running AI agent harness sessions on different machines talk to each other agent-to-agent, and (optionally) run commands on each other's machines over SSH. Design goals:

• Peer-to-peer -- no central server, no cloud, direct SSH between your machines
• Real-time push where the host supports it -- Claude Code receives <channel source="agent-bridge"> events; OpenClaw receives native channel turns through openclaw-channel/
• Small transport surface -- just bash/ssh for pairing and delivery, plus Node for the MCP/channel plugins; no Docker, no central service
• MCP tools + harness-specific receivers -- bridge_* tools are shared, but Claude Code's claude/channel stdio lifecycle and OpenClaw's registerChannel() gateway lifecycle are deliberately different

Current highlights (4.10.0)

Key changes through v4.10.0, grouped by feature area:

• Claude Code personas and named targets — Claude Code inboxes are persona-scoped (claude-code/default, claude-code/<persona>), with AGENT_BRIDGE_PERSONA as the session identity. Legacy target="claude-code" still rolls forward to the default persona, but new sends should be explicit.
• OpenClaw is a first-class peer — the openclaw-channel/ plugin is verified end-to-end and now uses agent-driven reply routing: the inbound turn carries bridge context, and the agent decides whether to reply via bridge and/or user-facing channels.
• Codex tasks are first-class endpoints — run agent-bridge codex bind inside a task to discover its thread id, derive a stable title-based alias, and start the background delivery service. Inbound messages queue while the task is busy and wake that exact persisted task through the public App Server; the task itself never polls.
• Routing and delivery hardening — targetless files are quarantined, same-machine sends use direct local inbox writes, subagents can long-poll with bridge_receive_messages(wait: true), and malformed or exhausted messages land under .failed/ for post-mortems.
• Runtime freshness and recovery — auto-update now has in-process notices, same-host coordination locks, plugin-registry rewiring, harness-independent periodic update scripts, migration-instruction injection, and more observability around channel recovery / inbox drains / orphaned MCP children.
• Compact relay expansion — OpenClaw relay receipts now show a short expand id plus agent-bridge relay-expand <id> instead of dumping long bridge message bodies into Telegram/user channels; the full message is stored locally under ~/.agent-bridge/relay-expand/ with TTL/bounded rotation.
• Version/status visibility — bridge relays include the running agent-bridge version, and claude_code_channel_status exposes the live plugin version / lease / watcher state for stale-runtime debugging.
• Docs/site catch-up — the README and GitHub Pages highlights now reflect the 3.14.x → 4.1.0 work instead of older 3.x-era assumptions.

See CHANGELOG.md for the commit-level history.

---

Notifications (4.8.0+)

agent-bridge can pop a native macOS notification banner on any Mac in the fleet — local or remote — via the bridge_notify MCP tool and the agent-bridge notify CLI verb.

This is a fire-and-forget side effect, NOT an agent message: it does not write to an inbox, does not wake or message the remote agent, and returns the real render success/failure synchronously. Use it for "task finished / build done / audio switched" style banners; for anything the remote agent must act on, use bridge_send_message.

Local-vs-remote routing:

• Local (--local): rendered in-process on this Mac. Pure-bash path — prefers terminal-notifier, falls back to osascript display notification when it's not installed.
• Remote (a machine name): SSHes to the target and runs the target's OWN agent-bridge notify --local …, so the remote machine renders it with its own notifier and reports its real exit status back.

# Pop a banner on this machine
agent-bridge notify --local --title "Build" --message "done"

# Pop a banner on a remote machine (renders there, via its own notifier)
agent-bridge notify Ethans-Mac-mini --title "Done" --message "task finished" --sound default

# Optional flags
agent-bridge notify --local --title "T" --message "M" --subtitle "S" --sound "Glass" --group "build"

The MCP equivalent is the bridge_notify tool (see INSTRUCTIONS.md) — same local/remote semantics, callable directly by an agent. Note: the running MCP child only exposes the bridge_notify tool after a full Claude Code restart; the agent-bridge notify CLI verb works immediately after build.

---

Shared context — fleet-wide learnings (4.9.0+)

Your fleet develops institutional memory. agent-bridge keeps a global shared-context store of learnings and findings that ANY agent on ANY paired machine — Claude Code, OpenClaw, Codex, whatever harness — can search before re-deriving a fix, and must contribute to when it discovers something globally useful.

Think of it as the fleet-wide layer on top of the memory you already have:

• Per-repo institutional memory → the repo's LEARNINGS.md (project-local fixes stay there).
• Per-harness memory → Claude Code auto-memory, OpenClaw workspace rules (machine/agent-private notes stay there).
• Fleet-wide → this store. OS gotchas, infra fix recipes, auth/API quirks, cross-machine workflows — anything a different agent on a different machine would benefit from.

Additive only — never a replacement. The shared context is an ADDITION to each harness's existing memory systems, not a new home for them. Agents keep recording everything exactly where they would have recorded it anyway (harness memory, repo LEARNINGS.md, workspace rules), and then also add a copy of the fleet-wide-applicable subset to the shared store. An agent must never skip or relocate a native memory write because the shared store has the content, and must never import existing harness memories into the store as a migration. When unsure: write both.

How it works:

• Every machine holds a full replica at ~/.agent-bridge/shared-context/learnings.ndjson (append-only NDJSON — greppable, jq-able, mergeable). Searches are pure local reads: no network, no latency.
• learnings add appends locally, then pushes to every paired machine over the same SSH side-effect path notifications use (the remote's own CLI validates + dedupes + appends — your machine never writes a peer's file directly).
• Offline peers just miss the push and reconcile later with agent-bridge learnings sync (bidirectional union). Every entry has a lowercase-uuid id, and ingest dedupes by id, so pushes, syncs, and replays are all idempotent.

# Record a learning that applies fleet-wide (pushes to all paired machines)
agent-bridge learnings add \
  --title "Surfshark IKEv2 password-dialog loop" \
  --body $'Symptom: recurring macOS VPN password dialog\nCause: stale IKEv2 keychain credential\nFix: switch protocol to WireGuard\nGuard: ...' \
  --tags macos,vpn,surfshark

# Search before debugging — another agent may have already solved it
agent-bridge learnings search surfshark
agent-bridge learnings search --tag vpn

# Reconcile with peers that were offline during a push
agent-bridge learnings sync --all

# Housekeeping
agent-bridge learnings list
agent-bridge learnings show <id>
agent-bridge learnings remove <id> --fleet   # plain remove is local-only; sync could resurrect it

The MCP equivalents are bridge_learnings_add and bridge_learnings_search — and the MCP server's instructions tell every connected agent the rule of the road: search the shared context when starting to debug something (an agent on another machine may already have the answer), and record any learning that could apply fleet-wide. Same restart caveat as other new tools: running MCP children expose the new tools only after a full harness restart; the CLI verbs work immediately.

---

Codex support (4.10.0+)

Codex tasks are first-class bridge endpoints, both directions:

• Any Codex task → any fleet target. Register the agent-bridge MCP server in ~/.codex/config.toml (tools-only — never set AGENT_BRIDGE_PERSONA for Codex) and the task gets the full bridge_* toolset. Set AGENT_BRIDGE_FROM_TARGET="codex/<alias>" in that MCP entry (or pass from_target per send) so replies route back to the task. No MCP in the session? agent-bridge codex send delivers over the same transport from any shell.

• Any fleet machine → a bound Codex task, pushed. An existing or new task opts in by binding a stable alias to its exact persisted thread — run this inside the task's shell:

  agent-bridge codex bind    # auto-discovers task id + title-derived alias
  

  It reads the task name without resuming it, creates a portable stable alias (for example Release Review → codex/release-review), suffixes only real name collisions, persists that endpoint across later title changes, and starts the service. Pass --alias release-review only when you want an explicit override. From then on bridge_send_message({ machine, target: "codex/release-review", ... }) lands in inbox/codex/release-review/, and the codex-channel daemon (auto-started, one lease per machine) resumes that exact thread over the public Codex App Server API and starts a turn with the message — queued while a turn is active, strict FIFO, crash-safe delivery state with a dedupe probe so a message is never lost and never double-delivered. Replies are one tool call: the injected [BRIDGE-CONTEXT] names the exact bridge_send_message invocation.

Safety: bridge-delivered turns never auto-approve anything (schema-exact declines, safe approvalPolicy=never + workspace-write sandbox defaults per turn, pre-bridge thread settings restored afterwards), and an ownership guard defers/releases while another Codex client is actively using the thread. The message fence is a prompt-boundary/integrity marker, not a trust sandbox: pairing a sender and binding an alias grants that sender user-prompt authority, including the ability to ask the model to use tools already exposed to the task. Codex 0.145 offers no per-turn tool allowlist/isolation; the approval and workspace controls prevent new escalation but do not remove existing MCP or other tools. Bind only for peers whose prompt/tool authority you accept. A separate honest caveat: Codex thread-store locks are process-local, so independent Codex clients share no cross-process lock — the guard (plus active-turn hydration on resume, bridge-owned-only steering, and prompt unsubscribe) narrows the race but does not eliminate it; avoid manually driving a bound task during bridge delivery, and ambiguous deliveries are dead-lettered rather than duplicated. Inspect everything with agent-bridge codex status / doctor. Requires Codex 0.145.0+. Full details, limitations and recovery: codex-channel/README.md.

---

Architecture overview

                          agent-bridge architecture

 MACHINE A (e.g. Mac Mini)                    MACHINE B (e.g. MacBook Pro)
 ┌─────────────────────────────────┐         ┌─────────────────────────────────┐
 │                                 │         │                                 │
 │  Agent (Claude/OpenClaw/Codex)  │         │  Agent (Claude/OpenClaw/Codex)  │
 │  ┌───────────────────────────┐  │         │  ┌───────────────────────────┐  │
 │  │ MCP Server / Channel      │  │   SSH   │  │ MCP Server / Channel      │  │
 │  │ ┌───────────────────────┐ │  │◄───────►│  │ ┌───────────────────────┐ │  │
 │  │ │ bridge_send_message   │ │  │messages │  │ │ bridge_send_message   │ │  │
 │  │ │ bridge_run_command    │ │  │         │  │ │ bridge_run_command    │ │  │
 │  │ │ bridge_status         │ │  │         │  │ │ bridge_status         │ │  │
 │  │ │ ...                   │ │  │         │  │ │ ...                   │ │  │
 │  │ └───────────────────────┘ │  │         │  │ └───────────────────────┘ │  │
 │  │ File watcher (inbox)      │  │         │  │ File watcher (inbox)      │  │
 │  └───────────────────────────┘  │         │  └───────────────────────────┘  │
 │                                 │         │                                 │
 │  agent-bridge CLI              │         │  agent-bridge CLI              │
 │  ~/.agent-bridge/              │         │  ~/.agent-bridge/              │
 │    config, keys/, inbox/       │         │    config, keys/, inbox/       │
 └─────────────────────────────────┘         └─────────────────────────────────┘

 Both machines are PEERS -- either can run commands on the other.
 No fixed controller or target.

The diagram shows the shared transport shape, not one identical host lifecycle. As of 3.7.0, the Claude Code integration uses one unified plugin at mcp-server/ that hosts both:

• The 13 user-facing bridge_* tools (and the diagnostic claude_code_channel_status status tool).
• The long-lived inbox watcher that holds a persona-scoped lease such as ~/.agent-bridge/locks/claude-code__default.watcher-lock.json, polls its active inbox such as ~/.agent-bridge/inbox/claude-code/default/ at 2 s, and pushes incoming messages back to Claude as notifications/claude/channel.

3.6.0 had split these into two plugins (an agent-bridge tools server + a separate agent-bridge-channel channel host). Production evidence showed Claude Code's plugin host actually gates idle-reaping on MCP tool-call frequency on stdio JSON-RPC, not channel registration — a channel-only plugin gets reaped after every notification regardless of Patches G/H. 3.7.0 re-merges everything so frequent bridge_* tool calls keep the plugin alive (same lifetime guarantees as Telegram). See CHANGELOG.md 3.7.0 entry. OpenClaw still ships its own native channel plugin in openclaw-channel/ — unaffected by the consolidation.

---

Compatibility

Agent Harness	Status	Integration
Claude Code	✅ Tested end-to-end, both machines confirmed	One unified plugin as of 3.7.0: the agent-bridge plugin (MCP server in mcp-server/) exposes bridge_* tools AND owns the watcher lease that pushes inbound messages via notifications/claude/channel. The frequent tool calls keep the plugin alive — same lifetime model as Telegram
OpenClaw	✅ Tested end-to-end, first-class channel	Separate native plugin in openclaw-channel/ registers with OpenClaw via api.registerChannel(); the MCP server is used for tools and runs tools-only
Codex CLI (OpenAI)	✅ Verified against Codex 0.145.0 App Server, first-class bound-task delivery	The tools-only MCP surface handles sends/binding/status; the background codex-channel/ service scans inbox/codex/<alias>/, resumes the exact persisted task, queues while active, and starts the inbound turn. The task itself never polls; this is explicit App Server turn injection, not a native harness channel push
Gemini CLI	🟡 Scaffolded, not exercised yet	MCP server + skill file at GEMINI.md; inbound receive/polling flow still needs harness-specific verification
Aider / other MCP hosts	🟡 Scaffolded, not exercised yet	MCP server + generic instructions at INSTRUCTIONS.md; inbound receive/polling flow still needs harness-specific verification

"Scaffolded" means the files exist and the MCP server is harness-agnostic for tools, but nobody has verified the remaining non-Claude/non-OpenClaw/non-Codex harnesses actually drive a complete receive/reply loop correctly. If you try one of those and it works (or doesn't), open an issue — empirical reports are welcome.

---

What it looks like

Step 1: Setup

Run on each machine you want to bridge:

$ agent-bridge setup

  +----------------------------------------------+
  |         agent-bridge  .  setup               |
  +----------------------------------------------+

  1. SSH Server
  [ok] SSH (Remote Login) is already enabled.

  2. SSH Key Pair
  Key pair generated.

  3. Pairing Token
  One-time pairing token generated.

  +====================================================================+
  |                    agent-bridge pairing                             |
  +--------------------------------------------------------------------+
  |  Machine:    MacBook-Pro                                           |
  |  User:       ethan                                                 |
  |  Local:      MacBookPro.local                                      |
  |  Local IP:   192.168.1.42                                          |
  |  Public IP:  82.45.123.67                                          |
  |  Port:       22                                                    |
  |  Token:      bridge-a7f3k9                                         |
  +--------------------------------------------------------------------+
  |  Public Key: ssh-ed25519 AAAA...long...key bridge:MacBook-Pro      |
  +====================================================================+

  Photograph this screen and send to Claude on your other machine.

Step 2: Pair

On the other machine, tell the agent the connection details (or paste the manual command). The public key from the setup screen is included -- no password needed:

$ agent-bridge pair \
    --name "MacBook-Pro" \
    --host 192.168.1.42 \
    --port 22 \
    --user ethan \
    --token bridge-a7f3k9 \
    --pubkey "ssh-ed25519 AAAA...key bridge:MacBook-Pro"

  1. Local Key Pair
  Using existing key pair for Mac-Mini.

  2. Authorize Remote Key
  [ok] Remote public key added to ~/.ssh/authorized_keys.

  3. Token Verification
  [ok] Token accepted: bridge-a7f3k9

  [ok] Paired with "MacBook-Pro"!

Step 3: Use

Talking to the running agent on the other machine — from inside an agent session (the main use case):

# From Claude Code on Machine A, the channel plugin gives you:
bridge_send_message({
  machine: "MacBook-Pro",
  message: "can you check whether the tests pass in ~/Projects/myapp and tell me what broke?",
  target: "claude-code/default"
})

# Over on MacBook-Pro, the running Claude session sees, pushed into its context:
<channel source="agent-bridge" from="Mac-Mini" message_id="msg-..." ts="...">
can you check whether the tests pass in ~/Projects/myapp and tell me what broke?
</channel>