Letterbox

Letterbox

📌 专为内部生产环境打造。 其架构已在数月的日常 AI 开发中得到验证。现已开源，作为参考实现。我几乎每天都会用它。

如果你在终端中使用 AI 编码助手，通常一次只能使用一个——要让两个助手协作，就得自己在窗口之间复制粘贴消息。Letterbox 可以让两个助手（比如 Claude 和 Gemini，或 Gemini 和 Mistral's Vibe）直接对话、协同完成任务，无需你动手。

效果： 一个 Agent 可以制定计划，另一个负责审查；也可以把工作分给两个 Agent——它们会自行协作，你只需旁观，无须手动转发每条消息。

一种基于文件的小型通信协议，让两个在不同终端中的 AI Agent 实时对话。

Letterbox 让两个终端编码 Agent——Claude Code、Gemini CLI、Antigravity 或 Mistral's Vibe——通过共享目录传递消息文件，进行实时对话。一个 Agent 发言时，系统会向另一个 Agent 的终端注入 📬 通知，唤醒它读取消息并回复。无需网络、无需服务、无需共享内存：只需文件夹中的 JSON 文件和操作系统的原子重命名操作。它原本是为内部规划循环打造的消息层，后于 2026 年提取出来，成为独立的版本化工具。如果你曾希望两个 CLI Agent 协同处理任务，而无须在窗口之间复制粘贴，那么这正适合你。作者偶尔会随兴更新（启动器会在有新版本时通知你）——但目前它只是一个不受支持的小型项目，并非社区项目。

该桥接支持跨运行环境：一端使用 Claude，另一端使用 Gemini，通过同一通道通信，已通过实时验证。唯一需要注意的是设置方式——Claude 会自动完成配置，而 Gemini 和 Antigravity 则从各自的设置中加载 letterbox。设置一节将介绍这两种方式。

为什么要开发它

我每天都与两位 AI 协作者——Claude 和 Gemini——一起工作，它们分别运行在各自的终端运行环境中（Claude Code、Gemini CLI、Antigravity CLI，以及现在的 Mistral's Vibe）。Letterbox 能让它们彼此对话，而不是通过我来传话。

这有两种使用方式。有时是手动：我们在头脑风暴，我想让另一个模型加入对话。有时是自动化——在规划循环中，Claude 起草计划，然后将每个计划发送给 Gemini，作为内置环节进行审查。Letterbox 用同一种方式处理这两种情况。

它在设计上与运行环境无关——Claude Code ↔ Gemini CLI ↔ Antigravity CLI ↔ Vibe，任意组合均可；相同模型组成的组合也同样适用：两个 Claude 标签页，或两个 Gemini 标签页，都能通过同一通道对话。

它是什么

每次运行 letterbox <harness>，都会在一个终端中启动两个协同工作的进程：

  letterbox claude --channel demo --as alice
        │
        ├─ PTY-Parent  (the foreground letterbox process)
        │    • spawns the harness CLI as a PTY child
        │    • watches the channel directory for peer writes
        │    • injects 📬 notifications into the PTY on arrival
        │
        └─ the harness spawns:
             └─ letterbox mcp  (stdio MCP server, agent-spawned)
                  • send_message / check_messages / acknowledge
                  • check_latest_message / channel_info / list_channels

  Both sides coordinate ONLY through the filesystem:

        ~/.letterbox/channels/demo/
          msg-*.json           ← one file per message
          .read/alice.json     ← per-agent read markers
          .read/bob.json

没有守护进程、没有 IPC，也没有后台服务。文件系统就是协同媒介——PTY-Parent 的监视器会发现新出现的 msg-*.json 并显示通知；通道目录持久、可检查，也可以用 cat 查看。由于内存中没有存放任何重要数据，崩溃恢复很简单。

Agent 获取 letterbox 工具的方式因 harness 而异，这是唯一需要配置一次的内容：

• Claude Code 接受启动标志，因此 letterbox 会自动完成配置——它会生成临时 MCP 配置，并将 --mcp-config 传给 claude。你无需进行任何设置。
• Gemini CLI 和 Antigravity 不接受该标志；它们从各自的设置文件中加载 MCP 服务。你只需在那里添加一条与通道无关的 letterbox 条目，之后启动器会在启动时通过环境变量向每个会话传递其通道和身份——因此无需针对每个通道编辑设置。
• Vibe 从 ~/.vibe/config.toml 加载 MCP 服务。它的 MCP 子进程只继承经过精简的环境，因此需要一次性设置一个桥接脚本，将 LETTERBOX_CHANNEL / LETTERBOX_SENDER 从 Vibe 自身进程的环境中传递过来。完成后，任何通道的使用方式都与 Gemini 完全相同。请参阅 Vibe 设置部分。

适用人群

• 使用终端编码 Agent，并希望在同一台机器上实现自主 AI↔AI 对话，无需在多个窗口之间手动复制粘贴的人。
• 看重以文件为事实来源的人——可审计、可搜索，没有不透明协议，也没有魔法。

不适用人群

• 想要使用托管或联网聊天服务的人——消息协议仅限本地文件系统，不会访问网络。（启动器会在启动时进行一次可选的尽力版本检查；可通过 LETTERBOX_NO_UPDATE_CHECK=1 禁用。）
• 想要使用多用户平台的人——它是同一台机器上 Agent 之间的点对点桥接，而不是多用户中枢（请参阅专为两方打造）。
• 原生 Windows 用户——v1 仅支持 POSIX（请参阅不支持的功能）。
• 想要使用有支持保障的产品的人——letterbox 有版本管理，作者偶尔也会随兴更新（有新版本时，启动器会告知你），但它没有路线图、没有 SLA，也不承诺接受功能请求或持续维护。请按现状使用；如果有帮助，可以拉取较新版本。

专为两方打造

Letterbox 本质上是一个双向桥接工具——它专为一方与另一方通信而设计和调优。三个或更多 Agent 可以共享一个通道：定向寻址（send_message(to="<label>")）和 participants 列表让这种用法可行，同一通道内的广播也会发送给所有人。但共享通道是一个广播总线——每条消息都会唤醒所有参与者。如果没有编排（轮流发言、指定协调者，或制定发言规则），一个包含 N 方的房间就会变成通知风暴，意外地快速耗尽模型的消息或使用量限额。如果你想加入三方或更多参与者，请自行安排协调者。底层机制会如实反映房间内的参与者；礼仪则由你自行把握。

安装

可通过 PyPI 和 MCP Registry 获取。

pip install letterbox

也可以从源代码安装：

pip install -e .          # or: pip install -e ".[dev]" for the test extras

这会将 letterbox 命令添加到你的 PATH 中。必须能通过命令名称解析该命令——每个 Agent 都会自行启动 letterbox mcp——因此这一步至关重要。请确认：

which letterbox           # note this absolute path; Gemini/Antigravity setup needs it

你还需要安装要启动的 harness（claude、gemini、antigravity 或 vibe），将其添加到 PATH 中，并登录。Letterbox 会为你启动它。

更新

Letterbox 有版本号（letterbox.__version__ 是唯一可信来源），并发布到 PyPI。在面向用户的启动时，CLI 会尽力检查一次（每天最多一次，缓存位于 ~/.cache/letterbox/），如果有更新版本，会打印一行提示。更新方法：

pip install --upgrade letterbox

这是 letterbox 唯一会进行的网络调用——消息协议完全在本地运行。检查设有严格的超时限制，并且失败时完全静默：如果无法连接 GitHub，它只会不打印任何内容，也绝不会延迟启动。letterbox mcp（Agent 的 stdio 服务）不会运行此检查。设置 LETTERBOX_NO_UPDATE_CHECK=1 可彻底禁用此功能。

按运行环境进行设置

每种运行环境只需设置一次。跳过你不会使用的运行环境。

Claude Code — 无需操作

Letterbox 会自动配置 Claude：启动时，它会写入一个临时 MCP 配置（模式为 0600），并将 --mcp-config <path> 传给 claude。Letterbox 工具只会出现在该会话中，不会出现在其他地方。无需编辑任何设置文件。

Gemini CLI — 两个一次性步骤

1. 注册 MCP 服务，在 ~/.gemini/settings.json 中进行（如果文件不存在，则创建该文件）。使用已安装的 letterbox 的绝对路径（见上方的 which letterbox），并且只传入 ["mcp"]——不要传入频道或身份：

{
  "mcpServers": {
    "letterbox": {
      "command": "/absolute/path/to/letterbox",
      "args": ["mcp"]
    }
  }
}

此条目有意不绑定特定频道。启动器会在启动时将 LETTERBOX_CHANNEL、LETTERBOX_SENDER 和 LETTERBOX_INSTANCE_ID 导出到 Gemini 的环境中，MCP 服务会读取这些变量——因此，同一个条目适用于所有频道，无需再次编辑。（这与 Forge 编排器通过环境变量传递频道的方式一致。）

2. 信任启动目录。 Gemini 拒绝在不受信任的目录中运行，除非交互式地询问 “你信任此文件夹吗？”——而阻塞式 TUI 提示会卡住自动化流程。请在 ~/.gemini/trustedFolders.json 中预先信任启动目录（或其父目录）：

{
  "/home/you/projects": "TRUST_PARENT"
}

TRUST_FOLDER 仅信任该目录；TRUST_PARENT 则信任该目录及其下的所有内容，因此一个条目即可覆盖你的所有项目文件夹。（提示：不要试图用 Gemini 的 --skip-trust 标志绕过此步骤——它会强制查找工作区系统提示词，即使在已受信任的目录中也会因此崩溃。请改为信任该文件夹。）

Antigravity（agy）

使用 letterbox agy … 启动（较长的形式 letterbox antigravity … 也可用——agy 只是与二进制文件名一致的别名）。Antigravity 与 Gemini 一样，通过相同的环境变量接收每次启动时的频道和身份；不同之处在于 MCP 服务的注册方式。agy 从插件加载 MCP 服务，因此你需要将 letterbox 安装为一个精简的本地插件（一个包含两个 JSON 文件的目录）：

# 1. Build the plugin (one directory, two files). Use the absolute
#    `letterbox` path from `which letterbox`.
mkdir -p ~/.letterbox/agy-plugin/letterbox
cat > ~/.letterbox/agy-plugin/letterbox/plugin.json <<'JSON'
{ "name": "letterbox", "version": "1.0.0",
  "description": "Letterbox file-based AI-to-AI comms bridge." }
JSON
cat > ~/.letterbox/agy-plugin/letterbox/mcp_config.json <<'JSON'
{ "mcpServers": { "letterbox": {
    "command": "/absolute/path/to/letterbox", "args": ["mcp"] } } }
JSON

# 2. Install it (and confirm).
agy plugin install ~/.letterbox/agy-plugin/letterbox
agy plugin list

mcp_config.json 不绑定特定频道，原因与 Gemini 的设置条目相同——启动器会在启动时通过环境变量传递频道和身份。与 Gemini 一样，agy 也会检查文件夹信任状态：它会读取 ~/.gemini/antigravity-cli/settings.json 中的 trustedWorkspaces 列表；如果启动目录尚未列入其中，请将其添加进去。

状态： PTY 层（双向通知和消息传递）已通过实时验证，上述插件安装也能顺利配置工具。agy 中工具的完整往返流程刚刚成功运行，并进行了少量测试——请将 Antigravity 视为三者中最新的一个，并报告任何异常。

Vibe（Mistral）

以 letterbox vibe … 启动。Vibe 从 ~/.vibe/config.toml 加载 MCP 服务，但它的 MCP 子进程只会继承精简后的环境变量（HOME、PATH、SHELL、TERM、USER、LOGNAME），因此 LETTERBOX_CHANNEL 等变量不会通过正常继承传递给它。一个简单的一次性桥接脚本可以在启动子进程时通过 /proc 从 Vibe 进程读取这些变量，解决这个问题。之后，任何频道都能像 Gemini 一样正常工作，无需针对每个频道编辑配置。

1. 安装桥接脚本（随 letterbox 提供）：

cp "$(python3 -c 'import letterbox.data, pathlib; print(pathlib.Path(letterbox.data.__file__).parent / "vibe-mcp-bridge.sh")')" \
   ~/.letterbox/vibe-mcp-bridge.sh
chmod +x ~/.letterbox/vibe-mcp-bridge.sh

2. 在 ~/.vibe/config.toml 中注册。将任何现有的 letterbox 条目替换为：

[[mcp_servers]]
name = "letterbox"
transport = "stdio"
command = "/home/YOU/.letterbox/vibe-mcp-bridge.sh"
args = []

使用实际的主目录路径（不要用 ~——Vibe 可能不会展开它）。该条目有意设计为与频道无关：桥接脚本会在运行时从 Vibe 进程的环境变量中读取频道和身份信息，就像 Gemini 从自身环境变量中读取它们一样。

**3. 完成。**任何频道都能正常工作：

letterbox vibe --channel blueberry-fields --as mistral

Vibe 还会使用 --yolo（自动批准）启动，这样注入的通知就能唤醒它，而不会被逐个工具的提示阻塞。

**注意：**桥接脚本使用 /proc/$PPID/environ 读取 Vibe 的环境变量——仅适用于 Linux，这与 letterbox 仅支持 POSIX 的立场一致。macOS 支持需要使用其他机制（ps -p $PPID -Ewww）；目前尚未提供。

状态：📬 已确认唤醒注入正常工作（STEP 0 已验证 Vibe 的 ChatTextArea 会覆盖 Enter 键以提交，因此适用标准 PTY 注入路径）。Vibe 是四者中最新的，如有异常请反馈。

快速入门

打开两个终端，让它们指向同一个频道，并使用不同的身份。未提供配置文件时，letterbox 的内置默认设置会提供共享的全局状态目录（~/.letterbox）。

一个真正的跨框架桥接——Claude 与 Gemini 对话（请先完成 Gemini 设置）：

# Terminal 1
letterbox claude --channel demo --as claude

# Terminal 2
letterbox gemini --channel demo --as gemini

如果想简单些，也可以使用两个相同的框架：

# Terminal 1
letterbox claude --channel demo --as alice

# Terminal 2
letterbox claude --channel demo --as bob

两个会话都会启动并安静待命。现在，在终端 1 中轻推 Agent——例如，“给你的伙伴发条消息。” 从此，每条 📬 通知都会唤醒另一个 Agent，使其读取并回复：这就是整个交接流程的核心。--as <label> 名称让对话记录更易阅读；在底层，消息过滤使用的是每次启动时生成的实例 ID，而不是标签。

几点实话：

• **你不需要亲自运行 letterbox mcp。**该子命令是 stdio MCP 服务，由框架启动——它是给 Agent 用的，不是给你用的。在终端中手动运行时，它会提示这一点并退出。
• **启动参数按设计是自主运行的。**Claude 适配器使用 --dangerously-skip-permissions 启动，Gemini 适配器使用 --yolo 启动，因为注入的消息无法唤醒被逐项操作审批提示阻塞的 Agent。如果你不接受这种取舍，letterbox 就不适合你——请在 letterbox.toml 中覆盖这些参数，或停止使用。

如需完整的讲解式演示（两位 Claude 争论热狗是不是三明治），请参阅 examples/two-claudes-debating/ 下的示例项目。

了解桥接状态

由于由设置接入的运行环境会在每次会话中加载 letterbox，因此即使没有活动桥接，Agent 也可能可以使用 letterbox 工具——例如，你从未通过 letterbox 启动过的普通 Gemini 会话。Letterbox 会妥善处理这种情况，并为 Agent 提供检查方式：

• 普通会话处于休眠状态，并非故障。 没有频道时，MCP 服务仍会连接（运行环境显示平静的“已连接”），但消息工具会保持安静——只有在实际调用时才会失败，并给出清晰、可操作的消息，不会自行报错。刻意使用普通会话时，绝不会收到垃圾消息；如果桥接确实配置错误，则会在 Agent 尝试通信时立即显现。
• channel_info 是 Agent 查询桥接状态的依据。 调用它即可在服务端获取答案：桥接是否处于活动状态？使用什么频道、身份是谁？对端是谁（根据其最近一条消息判断）、有多少条未读消息，以及对端上次发言是什么时候？不确定当前状况的 Agent 可以在发送消息前先查询——*“对端上次发言是 90 秒前”与“从未发言”*的含义截然不同。

监视和列出频道

在任意终端中，查看原始对话或现有频道：

letterbox tail --channel demo --follow   # stream messages as JSON, one per line
letterbox list-channels                  # list channels with last-activity

如需生成初始 letterbox.toml，而不是依赖默认设置：

letterbox init --channel demo            # writes ./letterbox.toml (project-local)
letterbox init --global                  # writes ~/.letterbox/config.toml instead

操作

• 读取消息可了解最新情况；收件箱会自动清空。 check_messages 会返回对端的未读消息，并在读取时推进该 Agent 的已读标记——因此，连续调用会依次读取积压的消息，清空后的收件箱也会保持为空，无需手动记录。check_latest_message 是一种不会推进标记的查看方式，适用于常见的*“他们刚才说了什么？”*场景；如需显式控制单条消息，则可以使用 acknowledge。
• 重启意味着重新开始，而非重放历史。 启动时，Agent 的已读标记会对齐到磁盘上最新的消息，因此它只会看到加入之后收到的消息——不会被上一会话中整个频道的历史消息淹没。历史记录仍然保留，需要时也可以访问（通过带有 since_id 游标的 check_messages）；只是不会强制推送给你。
• 消息保留需要手动处理。 消息会一直留在频道目录中，直到你清理；系统不会自动删除（通信基础设施不能接受意外删除）。每个 Agent 的 .read/ 标记会跟踪已读状态——它们只会推进标记，不会触碰文件，也不会影响对端看到的内容。
• 实用上限：每个频道约 10,000 条未清理消息。 超过此数量后，check_messages 和 list-channels 可能会出现明显延迟。达到该数量后应进行清理。
• letterbox prune 是安全释放空间的方式。 默认采用试运行模式——只会显示将要执行的操作，不会修改任何内容。--yes-i-am-sure 会将匹配的文件移至可恢复的 cold/ 子目录；--delete --yes-i-am-sure（双重确认）则会永久删除。这是 letterbox 中唯一具有破坏性的命令。

letterbox prune --channel demo --keep-last 100                   # preview (dry run)
letterbox prune --channel demo --keep-last 100 --yes-i-am-sure   # move to cold/
letterbox prune --help                                           # all selection rules

频道只是一个文件夹，因此也可以使用 rm -rf ~/.letterbox/channels/demo；letterbox 不会锁定任何内容。

安全模型

完整的威胁模型见 docs/PROTOCOL.md。简而言之：

• **通道上的对等 Agent 不可信。**其消息正文可能包含提示词注入载荷、ANSI 转义序列或 shell 元字符。Letterbox 将双方都视为不可信。
• 通知仅使用可信上下文进行渲染。📬 通知模板会替换来自监听器自身配置和观察结果的变量（{channel}、{sender}、{message_id}、{timestamp}）——绝不会使用对等方的消息载荷。恶意对等方可以在其文件中写入任何内容，但这些内容都不会进入注入的通知。只有当 Agent 显式调用 check_messages 时，消息正文才会显示出来。channel_info 中的对等方字段也是如此：它们是从流量中观察到的信息，仅供参考，绝不会用于通知。
• **没有执行路径。**Letterbox 从不对消息正文或元数据字段调用 exec、eval，也不会将它们交给 shell。子进程通过 argv 列表启动（绝不使用 shell=True），且仅用于启动 letterbox.toml 中配置的执行环境。
• **路径安全。**执行任何文件系统操作前，都会根据严格模式验证通道名称和消息 id——../etc 或任何包含斜杠的内容都会被拒绝。
• 文件系统权限。~/.letterbox/ 和通道目录均以 0700（仅用户可访问）权限创建；生成的 MCP 配置文件权限为 0600。

**letterbox 不会防御的情况：**本地用户账户遭到入侵（文件系统权限是唯一屏障）、所使用的执行环境自身存在提示词注入漏洞，或跨机器同步（NFS、syncthing）引入的信任边界。这并非静态加密或网络信任层——按设计，这些都不在范围内。

范围与非目标

letterbox 刻意不做的事情正是其设计重点，而非功能缺失：

• **不调用大模型。**Letterbox 从不调用语言模型、不消耗 token，也不持有 API 密钥。通知模板是渲染后的文本，不是提示词。
• **不采集遥测数据、指标或分析数据。**不会收集任何内容，也没有仪表板或使用情况跟踪。
• **不回连、不自动更新、不检查版本。**Letterbox 从不联系任何服务端。首次运行时不会发出任何提示。
• **不使用网络。**它仅在本地文件系统运行。跨机器使用由你的文件系统同步工具负责，与 letterbox 无关。

正是这些非目标，让 letterbox 保持精简、静默、易于审查且经久耐用。

无障碍访问

• 默认使用纯文本（--format=plain）——便于通过管道传输和屏幕阅读器读取；tail 会在 stdout 上输出消息 JSON，供 jq 使用。结构化／彩色输出为可选项（--format=rich）。
• 不只依赖颜色传达信息。--color=auto|always|never 独立控制颜色；颜色绝不会是传达状态的唯一方式。
• stdout 输出数据，stderr 输出日志——命令可顺畅地通过管道传输。
• **全程使用 UTF-8。**工具自身的字符串为英文；消息正文则使用你编写时所用的语言。
• **界面简洁平和。**没有加载动画、遥测横幅或升级提示。成功时不打扰，出错时信息清晰——错误会指出路径、行号或有效选项。

我们不支持的内容

**Letterbox v1 仅支持 POSIX（Linux 和 macOS）。**PTY 启动与注入层基于 POSIX 原语构建；通过标准库 pty 模块提供的 Windows 支持并不完整，因此不会随产品发布。如果你使用 Windows，v1 中的 letterbox 将无法运行——最好现在就知道，而不是遇到崩溃后才发现。

另请参阅

• examples/two-claudes-debating/ — 实践教程：两个 Claude Code 会话实时辩论。
• skills/letterbox/SKILL.md — 面向 Agent 的使用指南：大模型如何使用实时桥接（广播、定向消息、参与者）。
• skills/letterbox-setup/SKILL.md — 面向 Agent 的设置指南：每种宿主一次性的 MCP 接线、每个频道一个标签的规则，以及升级后的重新启动流程。
• docs/AGENT_POINTER.md — 一段简短的即插即用内容，可粘贴到项目的 CLAUDE.md / GEMINI.md / AGENTS.md 中，让 Agent 知道自己处于桥接中。
• 完整的文件格式和协议参考见 docs/PROTOCOL.md。
• DECISIONS.md — 每项关键决策背后的架构决策记录（ADR），包括每种宿主的 MCP 接线（ADR-054/055）、休眠模式和 channel_info 预言机（ADR-056）、提交时机修复（ADR-057）、自维护读取标记（ADR-058）、每个频道的重复实例防护（ADR-061）、N 方定向寻址 + 参与者（ADR-062），以及 Vibe 适配器 + Textual 提交约定（ADR-067）。
• LICENSE — MIT。

状态

Letterbox 是一个有版本号、不提供支持的制品，采用 MIT 许可证，位于 github.com/dovahkiin-v/letterbox。它以完整形态发布，并按文档所述保持原样，不征集贡献。它并未冻结：我几乎每天都在使用它。不过，我可能会随心所欲地发布后续版本，不设定时间表。启动器每天一次的更新检查会在有新版本时通知你（设置 LETTERBOX_NO_UPDATE_CHECK=1 可关闭检查）。实际含义请参阅 CONTRIBUTING.md。