agent-intercom

---

开始使用

npx agent-intercom install

只使用 Claude Code？可以将它作为插件安装：

/plugin install agent-intercom --marketplace iambashar/agent-intercom

_{使用早于 2.1.275 版本的 Claude Code 时：运行 /plugin marketplace add iambashar/agent-intercom，然后运行 /plugin install agent-intercom@agent-intercom。该插件还会添加一项技能，教 Claude 遵循邮箱约定。}

npx 命令会将 MCP 服务注册到它找到的每个 CLI。重启这些 CLI 后，每个 Agent 都会获得三个工具：mail_send、mail_check 和 mail_peers。然后用自然语言提出请求：

你 → Claude： 请让 codex 审查 src/parser.ts 中的差异，并等待它回复。

启用实时推送，这样就不必轮询。请全局安装，因为守护进程需要一个稳定的路径：

npm i -g agent-intercom
agent-intercom install --push

按 CLI 列出 install 所做的更改

CLI	注册方式	推送所需的额外设置
Claude Code	claude mcp add，用户级作用域	无；使用 Claude Code 的对等套接字
Codex CLI	在 ~/.codex/config.toml 中添加托管区块（先备份）	无；使用 Codex app-server 守护进程
Antigravity (agy)	agy mcp add	在 ~/.gemini/config/hooks.json 中添加会话钩子

使用 --only claude|codex|gemini 指定单个 CLI；使用 --local 固定到 git 检出版本，而不是使用 npx。运行 agent-intercom uninstall 可移除所有内容，包括推送守护进程。

说明

旧版 gemini CLI 不再接受个人 Google AI Pro 登录；Google 已将这些用户迁移到 Antigravity CLI（agy）。此处默认将其 Agent 命名为 gemini。

看看它如何运作

两个 Agent 都不需要轮询。请求发出后会立即作为新一轮对话出现在 Codex 中，回复也会以同样的方式传到 Claude。

你将获得

支持的 Agent

Agent	邮箱名称	消息如何到达打开的会话
	claude	Claude Code 的本地对等消息套接字，即 SendMessage 在会话间使用的通道。消息会标记为来自另一个会话。
	codex	Codex TUI 所使用的共享 app-server 守护进程：使用 turn/start，如果已有一轮对话正在运行，则使用 turn/steer。
	gemini	通过 agy agentapi send-message 发送到对话中。每个会话都会通过钩子注册一次。
任何其他 MCP 客户端	任意名称	不支持推送。它会使用 mail_check 读取消息，或使用 mail_check(wait_seconds=300) 阻塞等待。

工具	功能
mail_send(to, body, reply_to?)	将消息发送到另一个 Agent 的收件箱
mail_check(wait_seconds?)	读取并收取你的消息；使用 wait_seconds（最长 300 秒）时，会阻塞等待消息到达
mail_peers()	列出已知的 Agent

推送的工作原理

sequenceDiagram
    autonumber
    participant C as Claude Code
    participant M as ~/.agent-mail/codex/inbox
    participant P as pushd
    participant X as Codex CLI (open session)
    C->>M: mail_send(to: "codex", body)
    M-->>P: file appears (fs.watch, no polling)
    P->>M: claim: rename to <id>.json.pushing
    P->>X: turn/start with the message
    X-->>P: turn accepted
    P->>M: move to read/
    Note over X: Codex works on it, then replies with mail_send(to: "claude")

• 只投递一次。 守护进程会在推送前重命名消息，mail_check 会在读取前重命名。谁先完成重命名，谁就投递消息。

• 失败时安全回退。 推送失败时，文件会被放回收件箱，并在 30 s 后重试。如果没有打开的会话，消息会等待 mail_check 读取。

• 寻址。 使用 claude.<session-name>、codex.<thread-id-prefix> 或 gemini.<conversation-prefix> 选择会话。否则，消息会发送到最近活动的会话，或 ~/.agent-mail/routes.json 中指定的会话：

  { "claude": "api-server", "codex": "019f018a" }
  

警告

推送依赖这三个 CLI 中未公开说明的内部机制，更新可能在不另行通知的情况下改变这些机制。发生这种情况时，推送会失败并记录日志，邮件则会回退到收件箱。协议详情：docs/live-push.md。

不使用推送守护进程

• Claude Code：docs/claude-monitor.md。在 Monitor 工具中运行 agent-intercom watch claude，即可在邮件到达时唤醒会话。
• Codex：docs/codex-listen.md。使用循环调用 mail_check(wait_seconds=300) 的监听提示词。

跨机器通信

没有共享文件系统的机器（例如 GPU 服务或 HPC 集群）上的 Agent，可通过 SSH 使用 bridge.sh 加入。它会将每条消息传送到收件人所在的机器，拉取的邮件也会像其他邮件一样推送。

BRIDGE_HOST=gpu-box REMOTE_AGENTS="claude-gpu" ./bridge.sh

flowchart LR
    subgraph laptop["💻 Laptop"]
        A[claude] & B[codex] & G[gemini]
    end
    subgraph gpu["🖥️ gpu-box"]
        R[claude-gpu]
    end
    laptop <-- "bridge.sh · rsync over SSH" --> gpu

更多信息：docs/remote-bridge.md。

每个 CLI 使用多个会话

名称就是 AGENT_NAME。为每个会话指定不同的名称，例如 claude-api 和 claude-web：

npx agent-intercom install --only claude --claude-name claude-api

CLI

agent-intercom install [--only claude|codex|gemini] [--claude-name N] [--codex-name N] [--gemini-name N] [--local] [--push]
agent-intercom uninstall        MCP entries, agy hook and push daemon
agent-intercom push install     push daemon as a login service (launchd / systemd --user)
agent-intercom push uninstall
agent-intercom push run         push daemon in the foreground
agent-intercom status           unread/read counts per agent
agent-intercom watch <name>     one line per new message, without consuming it
agent-intercom serve            the MCP server on stdio

安全性

这是一个没有身份验证的本地邮箱。任何以你的身份运行的进程都可以写入 ~/.agent-mail/*/inbox，而且Agent 会将消息视为要执行的输入。开启推送后，这些输入无需你手动输入，就会到达已打开的会话。

• 将收件箱中的内容视为不可信文本。不要因为某条消息的指示，就让某个 Agent 批准破坏性操作。
• 推送的消息会标记为 [agent-intercom] message <id> from <sender>。Claude Code 还会将其标记为来自另一个会话，而不是你本人。
• 推送只会读取只有你的用户才能读取的令牌（~/.claude/sessions/*.key、agy 会话令牌），并且只与本地套接字通信。任何内容都不会离开这台机器。

如需报告问题，请参阅 SECURITY.md。设置 AGENT_MAIL_DIR 可更改邮箱位置，例如将其移至项目文件夹中。

🤝 参与贡献

欢迎贡献，无论是修正错别字，还是支持新的 Agent。

我想……	从这里开始
修复一些小问题	适合新手的问题
支持其他编码 Agent	docs/adding-an-agent.md
报告 CLI 更新后导致推送失效的问题	错误报告
提问或提出想法	讨论区

提交拉取请求前，请先阅读 CONTRIBUTING.md。所有参与者都应遵守行为准则。

开发

git clone https://github.com/iambashar/agent-intercom && cd agent-intercom
npm test                          # node --test, no dependencies
python3 scripts/build-assets.py   # rebuild the README artwork

运行时零依赖；需要 Node 20+。请参阅 CONTRIBUTING.md 和更新日志。