Об этом проекте

## Что такое postbag postbag — небольшой мост, позволяющий двум сессиям ИИ-кодирующих агентов, запущенным на одной машине, обмениваться письмами. Сессии могут быть одного вендора или разных — Claude Code и Codex, две сессии Claude Code, или две сессии Codex. Каждое письмо доставляется через механизм пробуждения получателя ("дверь"), добавляется в единый журнал и учитывается в рамках заданного человеком лимита писем. README предлагает следующие типичные сценарии: одна сессия проверяет diff другой, разделение задачи между двумя агентами с согласованием интерфейса по письму, или получение второго мнения без ручного копирования контекста. Разделение труда формулируется как "текст идёт через postbag, код — через git". ## Как это работает - `join` регистрирует дверь сессии в журнале под именем. Для Claude Code это сокет и токен пересессийной передачи сообщений, для Codex — id потока. - `send` стучится в зарегистрированную дверь (сокет или `codex queue`), затем под блокировкой файла добавляет письмо в журнал, чтобы одновременные письма получали разные номера и разделяли один бюджет. - `open` начинает следующий обмен из обычного терминала вне сессии. Письма нумеруются внутри обмена, бюджет общий для всех участников. Без `--limit` обмен содержит 12 писем. - `read` выводит имена в мешке, открытый обмен и записи. - Журнал в `~/.postbag/ledger.jsonl` — единственное состояние. Нет демона, опроса, хуков, сервера или конфигурационного файла. Установка того же `POSTBAG_LEDGER` в обеих сессиях и терминале даёт отдельный мешок. Получатель пробуждается с пронумерованным письмом, оставшимся количеством, телом и одной командой для ответа (отправка ответа через stdin). Последнее письмо обмена указывает не отвечать, а следующая отправка отказывает и просит агента обратиться к человеку. ## Требования Python 3.10 или новее, только стандартная библиотека; установка через `pipx install postbag`. Для сессии Claude Code нужны экспортированные `CLAUDE_CODE_MESSAGING_SOCKET` и `CLAUDE_CODE_MESSAGING_TOKEN`. Для Codex — команда `queue` из Codex 0.149, экспортированный `CODEX_SESSION_ID` и рабочая команда `codex queue --help`; `POSTBAG_CODEX` может указывать на нестандартный бинарник. Две сессии Claude требуют без Codex бинарника, две сессии Codex — без сокета Claude. ## Проверка и поддержка платформ README сообщает о живых тестах на macOS: версия 1.0.2 с Claude Code 2.1.263 и Codex 0.153.4 из ChatGPT desktop app, и версия 1.1.0 с двумя реальными сессиями Claude Code 2.1.263, включая двухсторонний обмен и отказ при исчерпании бюджета. Linux проходит CI, но живая доставка на нём не проверена, Windows не поддерживается. ## Ограничения и замечания по безопасности - Журнал хранит все токены сессий Claude и письма. Записи сохраняют файлу `0600`, а новым директориям — `0700`; существующую пользовательскую директорию не трогает. `read` скрывает поля двери, `cat` — нет, поэтому сырой файл следует держать в стороне от git, логов и скриншотов. - Письмо становится ходом пользователя в сессии получателя, обе сессии должны быть заслуживающими доверия. Сам postbag ничего не отправляет за пределы машины, но сессии вендоров пересылают письмо в свои модельные сервисы как обычный промпт. - Имя — это адрес, а не аутентификация. `open` отказывается запускаться внутри сессии. Эти проверки опираются на переменные сессий вендоров — защитный механизм от путаницы ролей, а не защита от другого процесса под тем же пользователем. - Автоматическая доставка в Claude с обходом разрешений наблюдалась на протестированных версиях; другие режимы могут удерживать письмо на подтверждение. Codex требует право записи в журнал и подключения к сокету Claude. - "Доставлено" означает отправлено через дверь, а не прочитано. Таймаут или крах между отправкой и записью оставляют письмо под вопросом, подтверждений и повторных попыток нет. ## Область применения и совместимость Поддерживается конфигурация из двух сессий. Три и более — экспериментально; `read` об этом сообщает и каждое письмо перечисляет зарегистрированные имена. Журналы 1.0 читаются без перезаписи, легаси-вендоры распознаются как `@claude` и `@codex`. Смешение сессии 1.0 и 1.1 не поддерживается, поскольку `send` версии 1.0 принимает только голые `claude` или `codex` и не может выполнить команду ответа, переносимую в письме 1.1; обе сессии должны быть обновлены и повторно выполнить `join`. После перезапуска сессия должна заново `join` под тем же именем, и команда ответа будет передана тому, кто держит имя в момент её выполнения. Репозиторий лицензирован MIT и включает концептуальный документ `CONCEPT.md`, changelog, руководство по участию и исследовательский документ, перечисляющий другие инструменты в этой области.