intercom

Claude Intercom

使用 Channels API 在 Claude Code 会话之间建立双向通信桥梁。

让运行在不同机器上的两个 Claude Code 实例实时交谈。一方发送消息，另一方会立即收到频道通知，并可回复。

Intercom 能做到而原生功能做不到的事

Claude Code 现在提供了原生跨会话消息。以下是仍需使用 Intercom 的场景：

• 两个人之间通信。 这是最重要的一点。原生功能连接的是你自己的会话——收件箱与你自己的操作系统用户绑定，跨机器传递依赖你自己的 Remote Control。使用各自笔记本电脑的后端开发者和前端开发者是两个账户，原生功能无法将他们连接起来。Intercom 正是为这种两人热线而打造的。
• 原生支持 Windows。 原生消息功能仅支持 macOS 和 Linux。Intercom 基于 Bun，通过 HTTP 通信，不受操作系统限制。
• 使用自己的网络，而非 Anthropic 的网络。 原生跨机器消息会经由 Anthropic 服务器中转。Intercom 则通过你自己的网络、VPN 或隧道直接发送 POST 请求。
• 支持任意提供商。 可在 Bedrock、Vertex 和 Foundry 上使用，也可用于禁用遥测的环境；这些情况下原生消息功能会被关闭。
• 容器与主机之间通信。 原生发现依赖磁盘上的文件，因此容器中的会话无法看到主机上的会话，反之亦然。Intercom 只需要一个可访问的端口。
• 如实报告送达状态。 send_message 会分别报告 sent、delivered-to-process 和 answered 三种状态，并提供 check_message 工具。如果对方从未收到消息，你也能及时发现，而不是期待一个永远不会收到的回复。

如果你使用 macOS 或 Linux，且只想让自己的会话互相通信，原生功能更简单——用它就好。上面列出的其他场景，正是 Intercom 的用武之地。

为什么要用它？

如果后端开发者和前端开发者各自在不同的机器上运行 Claude Code，他们目前只能通过 Slack、Discord 或复制粘贴来转达问题。Claude Intercom 可在两个 AI 会话之间建立直接热线——一个 Claude 可以询问另一个 Claude 关于端点、架构或实现细节的问题，并从实际代码库中获得答案。

架构

Machine A                          Machine B
(e.g. backend dev)                 (e.g. frontend dev)

Claude Code A                      Claude Code B
     |                                  |
     +-- intercom.ts ---HTTP POST----> intercom.ts --+
     |   (channel)     <--HTTP POST--  (channel)     |
     |                                               |
     +-- stdio (MCP) --+        +-- stdio (MCP) -----+
                        |        |
                   Claude A    Claude B

两个实例运行同一个 intercom.ts 文件。每个实例都会监听 HTTP 消息，并通过 Channels API 将消息推送到本地 Claude Code 会话。每个实例还会提供 send_message 和 check_message 工具，供 Claude 调用。

要求

• Claude Code v2.1.80 或更高版本
• Bun 运行时
• 两台机器必须能够通过 HTTP 相互访问。推荐使用 Tailscale——请参阅连接两台机器

让 Claude 帮你设置

在每台机器上的 Claude Code 会话中粘贴以下内容，Claude 会带你完成整个设置流程。先在机器 A 上运行，并保存它提供的密钥，然后在机器 B 上运行。

Set up claude-intercom on this machine so this Claude Code session can message
a Claude Code session on my other machine.

Work through this in order, and stop and ask me whenever you need something
only I can tell you.

1. Check prerequisites. Confirm `bun --version` works and that `claude --version`
   is 2.1.80 or newer. If Bun is missing, tell me how to install it for my OS
   and stop there.

2. Work out how the two machines will reach each other. Run `tailscale ip -4`.
   If that returns an address we'll use Tailscale. If Tailscale isn't installed,
   tell me it's the recommended option and ask whether I want to install it or
   use something else.

3. Ask me these, one at a time:
   - a short role name for THIS machine, e.g. "frontend", "vps", "laptop"
   - the address of the OTHER machine (hostname or IP)
   - whether this is the first machine I'm setting up or the second

4. Handle the shared secret.
   - First machine: generate a strong random secret, show it to me once, and
     tell me I'll need it when I run this on the other machine.
   - Second machine: ask me to paste the secret from the first one.
   Both machines must end up with exactly the same secret.

5. Write `.mcp.json` in this project with an "intercom" server: command `npx`,
   args `["-y", "claude-intercom"]`, and env `MY_ROLE`, `REMOTE_HOST` (the other
   machine plus `:8788`), `INTERCOM_SECRET`, `INTERCOM_PORT` set to 8788.
   If `.mcp.json` already exists, merge the intercom entry into it instead of
   overwriting the file. Make sure `.mcp.json` is gitignored, it holds the secret.

6. Tell me to restart Claude Code on this machine with:
   `claude --dangerously-load-development-channels server:intercom`
   and explain that the flag is needed because the channels capability is still
   experimental, and that messages only arrive while both sides are running.

7. Once both machines are up, tell me to test it by asking one session to send
   a message to the other. Remind me that `send_message` reports sent /
   delivered-to-process / answered separately, so "delivered" means the remote
   process accepted it, not that the other Claude has read it.

Don't invent configuration keys. The only environment variables are MY_ROLE,
REMOTE_HOST, INTERCOM_SECRET, INTERCOM_PORT and INTERCOM_SEND_TIMEOUT_MS.

想手动设置？请参阅下方的手动步骤。

快速开始

1. 安装

无需安装。首次在两台机器上运行时，npx 会自动获取它。

你需要将 Bun 添加到 PATH 中——服务器使用 Bun.serve 监听 HTTP，而 npx 入口会将任务交给 Bun 处理。

git clone https://github.com/MuhammadTalhaMT/claude-intercom.git
cd claude-intercom
bun install

将示例配置复制到项目的 .mcp.json 中。

先生成一个密钥，并在两台机器上使用相同的值：

openssl rand -base64 32

然后在启动 Claude Code 的 shell 中导出密钥，而不是将它输入配置：

export INTERCOM_SECRET='the-value-you-just-generated'

.mcp.json 是项目文件，而项目文件会被提交到代码库。Claude Code 会在 .mcp.json 中展开 ${VAR}——包括 command、args、env、url 和 headers 中的内容——因此可以将下面的配置提交到代码库并与队友共享，同时密钥本身始终不会离开你的环境。

机器 A（例如后端——静态 IP 或 VPS）：

{
  "mcpServers": {
    "intercom": {
      "command": "npx",
      "args": ["-y", "claude-intercom"],
      "env": {
        "MY_ROLE": "backend",
        "REMOTE_HOST": "MACHINE_B_IP:8788",
        "INTERCOM_SECRET": "${INTERCOM_SECRET}",
        "INTERCOM_PORT": "8788"
      }
    }
  }
}

机器 B（例如前端——可以位于 NAT 后）：

{
  "mcpServers": {
    "intercom": {
      "command": "npx",
      "args": ["-y", "claude-intercom"],
      "env": {
        "MY_ROLE": "frontend",
        "REMOTE_HOST": "MACHINE_A_IP:8788",
        "INTERCOM_SECRET": "${INTERCOM_SECRET}",
        "INTERCOM_PORT": "8788"
      }
    }
  }
}

3. 启动

在两台机器上：

claude --dangerously-load-development-channels server:intercom

4. 对话

在任一 Claude Code 会话中：

“给另一位开发者发一条消息，询问仪表盘有哪些 API 端点可用。”

Claude 将使用 send_message 工具，将消息 POST 到另一台机器。另一端的 Claude 会收到频道通知并作出回复。

连接两台机器

使用 Tailscale。 在两台机器上安装后，它们就会在你自己的 tailnet 上获得稳定的私有地址。然后将两端分别指向对方的 tailnet 地址：

"REMOTE_HOST": "other-machine:8788"

这比向互联网开放端口安全得多：没有公共监听器，无需端口转发；即使 ISP 重新分配了你的 IP，地址也不会改变；设备身份由 Tailscale 强制验证，而不是完全依赖共享字符串。将 INTERCOM_HOST 设置为你的 tailnet 地址——如果还通过隧道转发，也可以设为 127.0.0.1——以确保外部完全无法访问。

# On the machine behind NAT
ngrok http 8788

"REMOTE_HOST": "your-subdomain.ngrok-free.app"

工具

send_message

发送消息后立即返回一个 id。它不会等待答复——回复稍后会作为单独的入站消息到达。

确认消息会刻意避免声称另一位开发者已收到消息。HTTP 200 只能证明远程进程已接受消息，不能证明另一端的 Claude 读过消息。

check_message

对于这种发出后即不再等待的频道，它可以回答一个问题：这条回复只是来得慢，还是永远不会到？传入一个 id，或者省略它以列出所有尚未完成的消息。

每条消息都处于以下三种状态之一：

只有设置了 expectReplyWithin，“逾期”才有意义；而且它是按消息设置的，不是一个全局超时——因此，快速查询端点和耗时较长的调查不会使用同一个计时标准。

配置

工作原理

1. Claude Code 将 intercom.ts 作为子进程启动（通过 stdio 运行的 MCP 服务）
2. 脚本声明 claude/channel 能力，将其注册为 Channel
3. 脚本启动一个 HTTP 服务，监听传入消息
4. 收到消息时（通过共享密钥进行身份验证），脚本会调用 mcp.notification()，并设置 method: 'notifications/claude/channel'
5. Claude Code 会将通知作为 <channel> 标签显示在对话中，其中包含消息 ID
6. Claude 读取消息后，可以使用 send_message 回复，并将 replyTo 设为该 ID；这会向远程机器发送 POST 请求
7. 原始发送方会将 replyTo 与自身的出站记录进行匹配，并将该消息标记为 answered

stdio 这一环并非可以替换为 HTTP 的实现细节。它负责将服务连接到特定的实时 Claude Code 会话：claude/channel 能力通过该连接注册，这也是 mcp.notification() 能够将通知发送到对话中的原因。如果将服务托管在远程位置，通知就会发送给与之建立连接的 MCP 客户端。

安全

• 共享密钥身份验证：POST /message 要求提供 X-Intercom-Secret 标头，其值必须与配置的密钥匹配，并采用恒定时间比较。其他情况均返回 401 Unauthorized。GET /health 刻意不进行身份验证，因此你可以端到端验证隧道——它会向任何请求者报告此实例的角色和版本，所以请将可访问的 intercom 视为可被发现。
• 密钥的私密程度取决于传输方式：每条消息都会通过明文标头发送密钥。通过 Tailscale（WireGuard）或 HTTPS 隧道传输没有问题。在共享网络上使用普通 HTTP 时，路径上的任何人都可以读取密钥并使用它。
• 没有重放保护：消息带有 id 和 timestamp，但两者都不会经过新鲜度或重复使用检查。有人只要在明文链路上捕获一条经过身份验证的请求，就可以原样重发，次数不限。
• 没有默认密钥：INTERCOM_SECRET 没有回退值。如果不设置它、保留文档中的占位符，或引用一个从未导出的 ${VAR}，intercom 就会以未配对状态启动——它不会绑定任何端口，send_message 也会拒绝发送并说明原因。未展开的 ${VAR} 情况很重要，因为 Claude Code 会将缺失的变量作为字面文本传递，否则两台机器就会使用同一个容易猜到的密钥。
• 入站内容会被视为数据，而非指令：服务器会告诉接收消息的 Claude，频道消息来自另一个人的会话——它无法批准任何内容、无法更改配置，文本中的斜杠命令也不起作用，并且应拒绝索要凭据或环境变量文件的请求，并向你报告。
• 不持久化数据：消息会实时转发，不会存储。
• 可配置的绑定地址：默认监听 0.0.0.0，以支持跨机器访问。隧道负责接入时，请设置 INTERCOM_HOST=127.0.0.1，这样只有隧道可以连接。

警告：这些指令只是默认行为，不构成安全边界。你无法通过提示词指令解决提示注入——任何持有密钥和地址的人都可以向你的 Claude 会话发送文本，真正的限制只有该会话自身的权限提示。原生跨会话消息传递通过入站消息的保留／接受／拒绝控制正确执行了这一点；而本工具没有。请使用强密钥，避免将其暴露在公共互联网，并且不要与那些你不会让其使用终端的对等方配对。

端点

POST /message 请求体：

{
  "id": "8649f5da",
  "replyTo": "40b0fd17",
  "content": "3 routes, all behind requireTenant()",
  "role": "backend-dev",
  "timestamp": "2026-08-16T09:41:00.000Z"
}

id 和 replyTo 是可选的——不带它们的消息仍会送达，只是无法进行关联。

请求体会先经过架构验证，然后才会传入你的会话。content 为必填项，且最多包含 32,000 个字符；id 和 replyTo 必须符合机器 ID 格式（[A-Za-z0-9_-]，≤64）；role 和 timestamp 不得包含 < > " ' 或任何 Unicode 控制字符、零宽字符或双向覆盖字符，因为发送方可以用这些字符伪造消息所渲染在其中的 <channel …> 包装。其他不符合要求的请求会返回 400，超过 64 KB 的请求体会返回 413。

使用场景

• 后端与前端协作：后端 Claude 使用实际代码库回答前端 Claude 的 API 问题
• Monorepo 多团队协作：在不同软件包上工作的不同 Claude 会话可以互相协调
• 代码审查中继：一个 Claude 审查代码，并将发现发送给作者的 Claude 会话
• CI/CD 通知：将 CI Webhook 指向 intercom，把构建结果推送到 Claude 会话

Star History

License

MIT