Letterbox

📌 Создан для внутреннего продакшена. Архитектура проверена месяцами ежедневной разработки с ИИ. Открыт как эталонная реализация.

Простыми словами: Если вы используете ИИ-ассистентов для кодинга в терминале, обычно вы работаете с одним за раз — а чтобы заставить двух из них сотрудничать, приходится вручную копировать сообщения между окнами. Letterbox позволяет двум ассистентам (например, Claude и Gemini, или Gemini и Vibe от Mistral) общаться напрямую и совместно выполнять задачу, без вашего участия.

Результат: один агент может планировать, пока другой рецензирует, или они могут разделить работу между собой — сотрудничая самостоятельно, пока вы наблюдаете, вместо того чтобы вручную передавать каждое сообщение.

Маленький файловый протокол связи, который позволяет двум ИИ-агентам в отдельных терминалах общаться друг с другом в реальном времени.

Letterbox позволяет двум терминальным агентам кодинга — Claude Code, Gemini CLI, Antigravity или Vibe от Mistral — вести разговор в реальном времени, передавая файлы сообщений через общую директорию. Когда один агент говорит, в терминал другого внедряется уведомление 📬, которое будит его для чтения и ответа. Никакой сети, сервера или общей памяти: только JSON-файлы в папке и атомарный переименование ОС. Это слой обмена сообщениями, созданный для внутреннего цикла планирования, выделенный в отдельный версионируемый инструмент в 2026 году. Если вы когда-нибудь хотели, чтобы два CLI-агента сотрудничали над задачей без ручного копирования между окнами — это для вас. Инструмент получает occasional обновления по прихоти автора (лаунчер сообщает, когда выходит новая версия) — но он не поддерживается: нет дорожной карты, нет запросов функций, это не community-проект.

Мост действительно кросс-платформенный: Claude с одной стороны, Gemini с другой, общающиеся через один канал, были проверены вживую. Единственная загвоздка — настройка: Claude подключается автоматически, а Gemini и Antigravity загружают letterbox из своих собственных настроек. Раздел Setup описывает оба варианта.

Зачем это существует

Я каждый день работаю с двумя ИИ-коллегами — Claude и Gemini — каждый живет в своём терминальном окружении (Claude Code, Gemini CLI, Antigravity CLI, а теперь и Vibe от Mistral). Letterbox — это способ заставить их общаться друг с другом, а не через меня.

Это происходит в двух режимах. Иногда это вручную: мы брейнштормим, и я хочу подключить другую модель к разговору. Иногда это автоматически — в цикле планирования Claude составляет план, и каждый план направляется Gemini на рецензирование как встроенный этап. Letterbox обрабатывает оба случая одинаково.

Он не зависит от конкретной платформы по дизайну — Claude Code ↔ Gemini CLI ↔ Antigravity CLI ↔ Vibe в любой комбинации — и пары одной модели работают так же хорошо: две вкладки Claude или две вкладки Gemini, общающиеся по одному каналу.

Related MCP server: claude-intercom

Что это такое

Каждый запуск 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, нет фонового сервиса. Файловая система и есть среда координации — watcher PTY-Parent видит новый msg-*.json и отображает уведомление; директория канала долговечна, её можно просматривать и cat-ить. Восстановление после сбоев тривиально, потому что ничего ценного не хранится в памяти.

Как агент получает инструменты letterbox — зависит от конкретной платформы, и это единственное, что настраивается один раз:

• Claude Code принимает флаг запуска, поэтому letterbox подключает его автоматически — генерирует временный MCP-конфиг и передаёт --mcp-config команде claude. Вам ничего настраивать не нужно.

• Gemini CLI и Antigravity не принимают этот флаг; они загружают MCP-серверы из своего файла настроек. Вы добавляете туда однострочную, не зависящую от канала запись letterbox один раз, а лаунчер передаёт каждой сессии её канал и идентичность через переменные окружения при запуске — так что вам не нужно редактировать настройки для каждого канала.

• Vibe загружает MCP-серверы из ~/.vibe/config.toml. Его MCP-подпроцесс наследует только урезанное окружение, поэтому нужен одноразовый скрипт-мост для передачи LETTERBOX_CHANNEL / LETTERBOX_SENDER из окружения самого процесса Vibe. После этого любой канал работает точно так же, как Gemini. См. раздел Vibe setup.

Для кого это

• Люди, использующие терминальных агентов кодинга, которым нужен автономный диалог ИИ↔ИИ на одной машине, без ручного копирования между окнами.

• Люди, ценящие файлы как источник истины — проверяемые, доступные для grep, без непрозрачного протокола и магии.

Для кого это НЕ

• Тем, кому нужен хостингованный или сетевой чат-сервис — протокол сообщений работает только с файловой системой и никогда не касается сети. (Лаунчер делает одну необязательную, best-effort проверку версии при запуске; отключите её с помощью LETTERBOX_NO_UPDATE_CHECK=1.)

• Тем, кому нужна многопользовательская платформа — это точечный мост между агентами на одной машине, а не хаб для многих пользователей (см. Built for two).

• Пользователям Windows — v1 поддерживает только POSIX (см. What we don't support).

• Тем, кому нужен поддерживаемый продукт — letterbox версионируется и получает occasional обновления по прихоти автора (лаунчер сообщает, когда выходит новая версия), но нет дорожной карты, SLA и обязательств принимать запросы функций или продолжать поддержку. Используйте как есть; заберите новую версию, если она поможет.

Создан для двоих

Letterbox — это двусторонний мост по своей сути — один пир общается с одним пиром, именно для этого он спроектирован и настроен. Три и более агента могут делить канал: адресация (send_message(to="<label>")) и список participants делают это возможным, а широковещательные сообщения в одном канале достигают всех. Но общий канал — это шина вещания — каждое сообщение будит всех участников. Без оркестрации (поочерёдность, назначенный координатор или правила, кто когда говорит) комната с N участниками превращается в шторм уведомлений, который может удивительно быстро исчерпать лимиты сообщений/использования модели. Если вам нужно три и более — приносите своего дирижёра. Субстрат честно сообщает, кто в комнате; этикет — на вас.

Установка

Letterbox устанавливается из исходников (колесо можно собрать; в настоящее время оно не опубликовано на PyPI). Из корня репозитория:

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

Это помещает команду letterbox в ваш PATH. Команда должна разрешаться по имени — каждый агент сам запускает letterbox mcp — так что это критично. Проверьте:

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

Вам также понадобится установленная платформа, которую вы запускаете (claude, gemini, antigravity или vibe), в PATH и авторизованная. Letterbox запускает её за вас.

Обновление

Letterbox версионируется (letterbox.__version__ — единственный источник истины); поскольку нет релиза на PyPI, HEAD ветки main в git и есть релиз. При запуске с участием человека CLI делает одну best-effort проверку (не чаще раза в день, кэшируется в ~/.cache/letterbox/) и выводит однострочное уведомление, если существует более новая версия. Для обновления:

pip install --upgrade "git+https://github.com/dovahkiin-v/letterbox"

Это единственный сетевой вызов, который letterbox когда-либо делает — протокол обмена сообщениями полностью локальный. Он выполняется с жёстким таймаутом и полностью fail-silent: если не может связаться с GitHub, просто ничего не печатает и никогда не задерживает запуск. Он никогда не выполняется для letterbox mcp (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 отказывается работать в недоверенной директории без интерактивного запроса "do you trust this folder?" — а блокирующий TUI-запрос остановил бы автоматизацию. Предварительно доверьте директорию запуска (или родительскую) в ~/.gemini/trustedFolders.json:

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

TRUST_FOLDER доверяет ровно этой директории; TRUST_PARENT доверяет ей и всему, что внутри, так что одна запись покрывает все ваши проектные папки. (Совет: не используйте флаг --skip-trust от Gemini, чтобы обойти это — он вызывает поиск системного промпта рабочей области, который падает даже в уже доверенных директориях. Лучше доверьте папку.)

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 также проверяет доверие к папке: он учитывает список trustedWorkspaces в ~/.gemini/antigravity-cli/settings.json, поэтому добавьте туда директорию запуска, если её там ещё нет.

Статус: PTY-слой (уведомления + доставка сообщений, в обоих направлениях) проверен вживую, а установка плагина выше чисто подключает инструменты. Полный цикл с инструментами в agy недавно заработал и слегка протестирован — относитесь к Antigravity как к самому новому из трёх и сообщайте о любых странностях.

Vibe (Mistral)

Запускайте как letterbox vibe …. Vibe загружает MCP-серверы из ~/.vibe/config.toml, но его MCP-подпроцесс наследует только урезанное окружение (HOME, PATH, SHELL, TERM, USER, LOGNAME) — поэтому LETTERBOX_CHANNEL и т.д. не достигают его через обычное наследование. Небольшой одноразовый скрипт-мост исправляет это, читая их из процесса Vibe через /proc во время запуска. После этого любой канал работает точно так же, как 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); в настоящее время не поставляется.

Статус: 📬 инъекция пробуждения подтверждена и работает (ШАГ 0 подтвердил, что ChatTextArea у Vibe переопределяет 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 — например, «Отправь сообщение своему коллеге». После этого каждое уведомление 📬 будит другого агента для чтения и ответа: в этом и заключается вся суть передачи. Имена --as <label> делают стенограмму читаемой; под капотом фильтрация сообщений использует идентификатор экземпляра запуска, а не метку.

Пара честных замечаний:

• Вы никогда не запускаете letterbox mcp сами. Эта подкоманда — stdio MCP-сервер, запускаемый средой; она для агента, а не для вас. При запуске вручную в терминале она сообщает вам об этом и завершает работу.

• Аргументы запуска автономны по замыслу. Адаптер Claude запускается с --dangerously-skip-permissions, а адаптер Gemini — с --yolo, потому что инъецированные сообщения не могут разбудить агента, заблокированного запросом подтверждения каждого действия. Если такой компромисс вам не подходит, letterbox — не ваш вариант; переопределите аргументы в letterbox.toml или отойдите в сторону.

Полное пошаговое руководство с пояснениями (два Claude спорят, является ли хот-дог сэндвичем) см. в примере проекта в examples/two-claudes-debating/.

Понимание состояния моста

Поскольку среда, подключённая к настройкам, загружает letterbox в каждой сессии, у агента могут быть доступны инструменты letterbox без активного моста — например, обычная сессия Gemini, которую вы никогда не запускали через letterbox. Letterbox спокойно относится к этому и даёт агенту способ проверить:

• Обычная сессия находится в спящем режиме, а не сломана. Без канала MCP-сервер всё равно подключается (среда показывает спокойное «подключено»), но инструменты обмена сообщениями остаются тихими — они завершаются с понятным и действенным сообщением только если их действительно вызвать, и никогда сами по себе. Преднамеренная обычная сессия никогда не засоряется; действительно неправильно настроенный мост обнаруживается в момент, когда агент пытается заговорить.

• channel_info — оракул моста для агента. Вызов этого инструмента даёт ответ на стороне сервера: активен ли вообще мост? На каком канале, под каким именем? Кто коллега (определяется по его последнему сообщению), сколько непрочитанных и когда он говорил последний раз? Агент, не уверенный в своей ситуации, может спросить перед отправкой — «коллега говорил 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 возвращает непрочитанные сообщения коллеги и продвигает маркер чтения этого агента по мере работы — так последовательные вызовы пролистывают накопленные сообщения, а опустошённый ящик остаётся опустошённым, без ручного учёта. check_latest_message — это не продвигающий взгляд для распространённого вопроса «что он только что сказал?», а acknowledge существует для явного управления отдельными сообщениями.

• Перезапуск — это новое начало, а не повтор. При запуске маркер чтения агента выравнивается по самому новому сообщению, уже находящемуся на диске, поэтому он видит только то, что приходит после его присоединения — его не зальёт всей историей канала из предыдущей сессии. История по-прежнему доступна и достижима по запросу (check_messages с курсором since_id); она просто не навязывается вам.

• Хранение вручную. Сообщения живут в каталоге канала, пока вы их не подрежете; автоматического удаления нет (неожиданное удаление неприемлемо в коммуникационной инфраструктуре). Маркеры .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. Вкратце:

• Агент-коллега на канале не заслуживает доверия. Его тела сообщений могут содержать полезные нагрузки для инъекции в промпт, ANSI-escape-последовательности или метасимволы оболочки. Letterbox считает обе стороны недоверенными.

• Уведомления рендерятся только из доверенного контекста. Шаблон уведомления 📬 подставляет переменные, взятые из собственной конфигурации и наблюдений наблюдателя ({channel}, {sender}, {message_id}, {timestamp}) — никогда из полезной нагрузки сообщения коллеги. Злонамеренный коллега может записать что угодно в свой файл; ничто из этого не попадает в инъецированное уведомление. Тела сообщений отображаются только когда агент явно вызывает check_messages. То же самое касается полей коллеги в channel_info: они наблюдаются из трафика и носят информационный характер, никогда не попадают в уведомление.

• Нет пути выполнения. Letterbox никогда не выполняет exec, eval или оболочку для тела сообщения или поля метаданных. Дочерние процессы запускаются со списками argv (никогда shell=True) и только для запуска среды, настроенной в letterbox.toml.

• Безопасность путей. Имена каналов и идентификаторы сообщений проверяются по строгому шаблону перед любой операцией с файловой системой — ../etc или что-либо со слэшем отклоняется.

• Права файловой системы. ~/.letterbox/ и каталоги каналов создаются с правами 0700 (только для пользователя); сгенерированный MCP-конфиг — 0600.

От чего letterbox НЕ защищает: скомпрометированная локальная учётная запись пользователя (права файловой системы — единственный барьер), собственные уязвимости инъекции в промпт потребляющей среды или границы доверия, введённые синхронизацией между машинами (NFS, syncthing). Это не слой шифрования в состоянии покоя или сетевого доверия — это вне области действия по замыслу.

Область применения и анти-область

То, что letterbox намеренно не делает, — это суть, а не пробел:

• Нет вызовов LLM. Letterbox никогда не вызывает языковую модель, не тратит токены и не хранит ключи API. Шаблон уведомления — это отображаемый текст, а не промпт.

• Нет телеметрии, метрик, аналитики. Ничего не собирается, нет дашбордов, нет отслеживания использования.

• Нет связи с домом, автообновления, проверки версий. Letterbox никогда не связывается с сервером. Первый запуск молчалив.

• Нет сети. Он локальный для файловой системы. Использование между машинами — это дело вашей синхронизации файлов, а не letterbox.

Эта анти-область позволяет letterbox быть маленьким, инертным, проверяемым и долговечным.

Доступность

• Обычный текст по умолчанию (--format=plain) — удобно для конвейеров и программ чтения с экрана; tail выводит JSON сообщений в stdout для jq. Структурированный/цветной вывод — по желанию (--format=rich).

• Нет сигнализации только цветом. --color=auto|always|never управляет цветом независимо; цвет никогда не является единственным способом передачи состояния.

• stdout — данные, stderr — журналы — команды чисто передаются по конвейеру.

• UTF-8 повсюду. Собственные строки инструмента — на английском; тела сообщений — на любом языке, на котором вы пишете.

• Спокойная поверхность. Нет спиннеров, баннеров телеметрии, назойливых обновлений. Тихий успех, понятные ошибки — ошибки указывают путь, строку или допустимые параметры.

Что мы не поддерживаем

Letterbox v1 — только POSIX (Linux и macOS). Слой запуска и инъекции через PTY построен на примитивах POSIX; поддержка Windows через модуль stdlib pty неполна и не поставляется. Если вы на Windows, letterbox не будет работать у вас в v1 — лучше знать сейчас, чем столкнуться с крахом.

См. также

• examples/two-claudes-debating/ — практическое руководство: две сессии Claude Code, спорящие в реальном времени.

• skills/letterbox/SKILL.md — руководство по использованию для агента: как LLM использует живой мост (рассылка, адресные сообщения, участники).

• skills/letterbox-setup/SKILL.md — руководство по настройке для агента: одноразовое подключение MCP для каждой среды, правило «одна метка на канал» и процедура перезапуска после обновления.

• docs/AGENT_POINTER.md — короткий встраиваемый блок для вставки в CLAUDE.md / GEMINI.md / AGENTS.md проекта, чтобы агент знал, что он на мосту.

• Полный справочник по формату файлов и протоколу — в 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. Он поставляется полным и работает как задокументировано; это личный артефакт, а не продукт, и он не ищет вклада. Неподдерживаемый означает отсутствие дорожной карты, SLA и обещаний исправлять проблемы или принимать запросы функций — но он не заморожен: автор может выпустить более позднюю версию по своему усмотрению, без графика. Ежедневная проверка обновлений в лаунчере сообщает вам, когда это происходит (LETTERBOX_NO_UPDATE_CHECK=1 для отключения). См. CONTRIBUTING.md о том, что это значит на практике.