postbag

## O que é postbag postbag é uma pequena ponte que permite a duas sessões de agentes de codificação com IA rodando na mesma máquina escreverem cartas umas para as outras. As sessões podem ser do mesmo fornecedor ou de diferentes — uma sessão Claude Code e uma Codex, duas sessões Claude Code ou duas sessões Codex. Cada carta é entregue por meio do mecanismo de despertar do próprio fornecedor receptor ("porta"), é adicionada a um único ledger compartilhado e é contada contra um orçamento de cartas definido por um humano. Usos típicos que o README sugere: ter um agente revisando o diff do outro, dividir uma tarefa entre dois agentes e concordar com a interface por carta, ou obter uma segunda opinião sem colar contexto manualmente. O README define a divisão de trabalho como "texto viaja por postbag, código viaja por git". ## Como funciona - `join` registra a porta de uma sessão no ledger sob um nome. Para Claude Code, esse é o soquete de mensagens por sessão e o token; para Codex, é o ID da thread. - `send` bica na porta registrada (o soquete, ou `codex queue`) e então adiciona a carta sob um bloqueio de arquivo, para que cartas simultâneas tenham números distintos e compartilhem um único orçamento. - `open` inicia a próxima troca a partir de um terminal normal, fora de qualquer sessão. As cartas são numeradas dentro de uma troca, e o orçamento é compartilhado por todos na bolsa. Sem `--limit`, uma troca possui 12 cartas. - `read` imprime os nomes atualmente na bolsa, a troca aberta e os registros. - O ledger em `~/.postbag/ledger.jsonl` é o único estado. Não há daemon, polling, hooks, servidor ou arquivo de configuração. Definir o mesmo `POSTBAG_LEDGER` em ambas as sessões e no terminal cria uma bolsa separada. O destinatário desperta com uma carta numerada, a contagem restante, o corpo e o único comando para respondê-lo (um `send` com a resposta no stdin). A última carta de uma troca diz para não responder, e o próximo send recusa e diz ao agente para parar e perguntar ao humano. ## Requisitos Python 3.10 ou posterior, apenas biblioteca padrão; instalável via `pipx install postbag`. Uma sessão Claude Code precisa de seu soquete de mensagens por sessão exportado através de `CLAUDE_CODE_MESSAGING_SOCKET` e `CLAUDE_CODE_MESSAGING_TOKEN`. Uma sessão Codex precisa do comando `queue` introduzido no Codex 0.149, `CODEX_SESSION_ID` exportado e um `codex queue --help` funcional; `POSTBAG_CODEX` pode apontar para um binário não padrão. Duas sessões Claude não precisam do binário Codex, e duas sessões Codex não precisam do soquete Claude. ## Verificação e suporte de plataforma O README relata verificação em tempo real no macOS: versão 1.0.2 com Claude Code 2.1.263 e Codex 0.153.4 do aplicativo desktop ChatGPT, e versão 1.1.0 com duas sessões reais Claude Code 2.1.263, incluindo uma troca bidirecional e a recusa de orçamento gasto. Linux passa no CI mas a entrega ao vivo é descrita como não verificada lá, e Windows não tem suporte. ## Limites e notas de segurança - O ledger armazena todos os tokens das sessões Claude bem como as cartas. As gravações mantêm o arquivo em `0600` e novos diretórios de estado em `0700`; um diretório personalizado existente é deixado intacto. `read` oculta os campos da porta, `cat` não oculta, então o arquivo bruto deve ser mantido fora de git, logs e capturas de tela. - Uma carta se torna uma virada do usuário na sessão destinatária, então ambas as sessões devem ser confiadas com a tarefa. postbag em si não envia nada para fora da máquina, mas as sessões dos fornecedores encaminham a carta para seus serviços de modelo como qualquer prompt. - Um nome é um endereço, não autenticação. `open` recusa executar dentro de uma sessão. Essas verificações leem as variáveis de sessão dos fornecedores — uma barreira contra papéis misturados, não proteção contra outro processo rodando como o mesmo usuário. - Entrega desacompanhada para Claude foi observada com permissões de bypass nas versões testadas; outros modos podem reter a carta para aprovação. Codex precisa de permissão para escrever o ledger e conectar-se ao soquete Claude. - "Entregue" significa submetido pela porta, não lido. Um timeout ou crash entre submissão e registro deixa uma carta em dúvida, e não há acknowledgements ou retries. ## Escopo e compatibilidade Duas sessões são a configuração suportada. Três ou mais é descrito como experimental; `read` informa isso e cada carta lista então os nomes registrados. Ledgers escritos por 1.0 são lidos sem reescrita, com pares legados de fornecedores lidos como `@claude` e `@codex`. Misturar uma sessão 1.0 com uma 1.1 não é suportado, porque um `send` 1.0 aceita apenas `claude` ou `codex` nu e então não consegue executar o comando de resposta carregado em uma carta 1.1; ambas as sessões devem ser atualizadas e pedir para `join` novamente. Após uma reinicialização, uma sessão deve `join` novamente sob o nome que possuía, e um comando de resposta alcança quem quer que possua o nome quando ele for executado. O repositório é licenciado sob MIT e inclui um documento conceitual sob a forma de `CONCEPT.md`, um changelog, diretrizes de contribuição e um documento de pesquisa listando outras ferramentas no espaço.