Skip to main content
Glama
cc-msg-bridge

cc-msg-bridge

by 0xnolanyu

cc-msg-bridge (CLI: cc-bridge)

EN — Turn any local process (a DSH session, a script, CI) into a first-class cross-session messaging peer of Claude Code, by speaking CC's native SendMessage wire protocol directly. Nothing to install on the Claude Code side; no patching, no UI automation, no API key.

中文 — 让任意本地进程(DSH 会话、脚本、CI)成为 Claude Code 的一等跨会话通信 peer:原生直连 CC 内部 SendMessage 的 wire 协议。CC 侧零安装、零破解、零 UI 自动化、不需要 API key。

any local agent ──(MCP / CLI)── cc-bridge ══(named pipe + auth)══ Claude Code sessions
  (DSH, scripts, CI)                        (VS Code / CLI / headless / bg 一视同仁)

What it does / 它能做什么

Tool

Description

cc_who

List every live Claude Code session on this machine (name, status, cwd, sessionId) / 列出本机所有在线 CC 会话

cc_send

Inject a message straight into a CC session's conversation queue; idle sessions are woken automatically / 把消息直接注入某个 CC 会话,空闲会话自动唤醒

cc_recv

Long-poll a real inbox — messages CC sessions send back via SendMessage arrive as push, not polling / 长阻塞收 CC 回信(真·推送)

cc_status

Bridge health + delivery log / 桥接健康状态与投递日志

Zero config on the Claude Code side: CC sessions simply see dsh-bridge in their peer list and reply with SendMessage to="dsh-bridge". CC 侧零配置:会话在 peer 列表里看到 dsh-bridge,SendMessage to="dsh-bridge" 即可回信。

Related MCP server: agent-bridge

Install / 安装

# 1. CLI (this repo)
npm i -g cc-msg-bridge       # published package / 已发布包名

# 2. DSH plugin bundle (plugin/ directory) — inside a DSH session with full access:
#    plugin_manager install_bundle → path/to/cc-bridge/plugin
#    tools appear as mcp__cc-bridge__cc_send etc.

CLI usage (works without DSH) / CLI 用法

cc-bridge who                            # list peers / 列 peer
cc-bridge send eng-agent "任务:跑测试"   # inject by name / 按名字注入
cc-bridge send loop-eng "状态?"          # idle sessions get woken / 空闲会话唤醒
cc-bridge recv 60                        # wait up to 60s for replies / 等 60s 收消息
cc-bridge mcp                            # stdio MCP server (what DSH spawns) / DSH 用这个

How it works / 机制

Reverse-engineered from the Claude Code binary and verified on the wire (full details in PROTOCOL.md): 以下全部为对 CC 二进制逆向所得并经线上抓包验证(详见 PROTOCOL.md):

  1. Every CC session publishes a live record at ~/.claude/sessions/<pid>.json (including its inbox pipe address) and writes a peer auth key to <pid>.<sha256(lowercased pipe path)>.key / 每个会话在注册表发布活记录与收件箱管道地址,并把 peer 认证 key 按"pid+管道哈希"落盘。

  2. Sending = connect to the target's inbox pipe, write an auth line {type:'auth', token:<target key's peerToken>}, then a user frame (cross-session-message envelope), disconnect; idle targets get a notify_when_idle control frame to wake them / 发送=连对方收件箱管道,auth 行+user 帧;空闲对方另发 notify_when_idle 唤醒。

  3. cc-bridge itself registers as a peer, so CC replies with its own native SendMessage tool — the last hop is the genuine article, nothing forged / cc-bridge 自身也注册为 peer,CC 用它自己的 SendMessage 本尊回信,最后一跳零伪造。

Environment / 环境变量

Variable

Default

Description

CC_BRIDGE_NAME

dsh-bridge

Name registered in the CC peer list / 注册到 CC peer 列表的名字

CC_BRIDGE_PIPE

\\.\pipe\cc-msg-<name>

Inbox pipe / 收件箱管道

CC_BRIDGE_SESSIONS_DIR

~/.claude/sessions

Registry dir (for tests) / 注册表目录(测试用)

CC_BRIDGE_INBOX_FILE

~/.cc-bridge/inbox.jsonl

Persistent inbox; one JSON line per received message, tail-able by external programs / 收件落盘,外部程序可 tail

Compatibility / 兼容性

  • Claude Code ≥ 2.1.327 (v2 protocol; verified against 2.1.329)

  • Windows (named pipes). macOS/Linux use Unix domain sockets with a different path convention — untested.

  • Node ≥ 14, zero dependencies.

Risks / 风险

The protocol is reverse-engineered, not an official commitment. If a CC upgrade changes fields, cc-bridge fails loudly (it never silently drops messages) — update the package then. 协议为逆向所得,非官方承诺。CC 升级若改字段,cc-bridge 显式报错(绝不静默丢消息),届时更新本包。

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      8
      26 npm
      3
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude Code, Codex and opencode sessions on the same machine to message each other live over a local pipe, with threaded replies and offline queuing, and to delegate or spawn one another as background subagents. Messages persist in SQLite and any running server can take over as broker, so peers stay reachable without a daemon.
      4
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables Claude Code to hand reviews, second opinions and tasks to the Codex and Antigravity desktop apps on one Windows PC and receive their answers back, without copy-pasting between apps. Each agent keeps working in its own app, with message threading, reply waiting, file reservations and delivery tracking over a local daemon.
      20
      1
      MIT