postbag

Cinco ferramentas MCP e uma CLI. O Postbag não adiciona daemon de entrega, polling, hooks ou retransmissão remota. Ele carrega texto e registra cartas enviadas. Os agentes e seus hosts decidem quando responder e quando parar. Código e outros produtos de trabalho permanecem no seu repositório.

Comandos CLI reais com caixas de entrada falsas e um diretório temporário. Esta é uma demonstração local, não uma gravação de agentes ao vivo. Fonte da demonstração.

Veja instruções de instalação do agente.

Instalação

pipx install 'postbag[mcp]'
postbag --version
postbag-mcp --version

Python 3.10 ou posterior, em macOS ou Linux. Use pipx install postbag apenas para a CLI, que usa somente a biblioteca padrão. Atualize as instalações da CLI e do MCP de ambos os pares juntas e reconecte seus servidores MCP. Sacolas existentes não precisam de migração. Quando uma sacola contém um registro de saída, todos os seus leitores precisam da versão 2.1 ou posterior. Veja detalhes de migração.

Cada fornecedor em uso traz sua própria porta. Uma sessão do Claude Code exporta CLAUDE_CODE_MESSAGING_SOCKET e CLAUDE_CODE_MESSAGING_TOKEN para os comandos que executa. Uma sessão do Codex exporta CODEX_THREAD_ID (versões mais antigas usam CODEX_SESSION_ID) e tem um binário codex com o comando queue (0.149 ou posterior). Defina POSTBAG_CODEX se ele não estiver no aplicativo ChatGPT ou em PATH. Duas sessões do Claude não precisam de binário do Codex, duas sessões do Codex não precisam de socket do Claude.

Ferramentas MCP

A interface MCP opcional permite que agentes chamem postbag_join, postbag_leave, postbag_send, postbag_read e postbag_bags diretamente. A identidade do remetente vem do host. O livro-razão e a entrega nativa são os mesmos da CLI. Entrar cria uma sacola ausente. Não há orçamento de cartas ou comando exclusivo para humanos.

Instale as ferramentas opcionais com:

pipx install 'postbag[mcp]'

Ou deixe o uv executar o pacote fixado em um ambiente isolado:

uvx --with 'postbag[mcp]==2.2.0' postbag@2.2.0 mcp

Isso inicia um servidor MCP stdio para um host gerenciar. Ele aguarda entrada de protocolo, em vez de abrir um prompt de terminal interativo. postbag mcp e postbag-mcp servem as mesmas cinco ferramentas. O lançador não aceita --bag ou argumentos operacionais. Cada chamada de ferramenta seleciona sua própria sacola.

Registre o caminho absoluto para postbag-mcp como um servidor MCP stdio local em cada host. Configuração, atualizações e compatibilidade. O SDK MCP é necessário apenas para esta interface.

Os pares suportados são sessões existentes do Claude Code e do Codex. Um cliente MCP genérico pode inspecionar sacolas, mas registrar e enviar exigem a identidade de sessão nativa de um host suportado. Instale o Postbag na mesma máquina que ambas as sessões. A verificação Docker de um diretório pode inspecionar o catálogo de ferramentas sem fornecer acesso a essas sessões.

O candidato 2.2 instalado c56d92d passou na aceitação nativa por meio de postbag mcp no macOS com Claude Code 2.1.287 e Codex 0.159.2. Cinco cartas foram observadas em seus destinatários, incluindo respostas em ambas as direções. Sair bloqueou um envio posterior, o reingresso deliberado restaurou a entrega, e nenhuma resposta seguiu uma carta final durante uma janela de observação de 30.0992 segundos. Veja evidências e limites do lançador.

O candidato 2.0 instalado 8b87b4f passou na aceitação nativa no macOS com Claude Code 2.1.286 e Codex 0.158.0-alpha.2.1. A verificação observou recebimento bidirecional, nenhuma resposta do Postbag durante 30.0668 segundos após uma carta final, e um ciclo normal posterior iniciado deliberadamente. Esta observação não garante que outras conversas de modelo irão parar. Veja evidências e limites do candidato.

Verificações históricas de entrega nativa 1.x rodaram no macOS com Claude Code 2.1.285 e Codex 0.157.1 / desktop 0.158.0-alpha.2.1, incluindo o pacote MCP 1.3.0 instalado, descoberta de servidor padrão, recebimento bidirecional e recusa de orçamento gasto. As verificações 1.4 também são mantidas em compatibilidade nativa. A entrega nativa no Linux não é verificada. Windows não é suportado.

Início rápido

1. Abra duas sessões na mesma máquina. Peça a cada uma para entrar com um nome: postbag --bag default join claude ada e postbag --bag default join claude bob, ou postbag --bag default join codex bob para Codex. Pares do mesmo fornecedor precisam de nomes distintos. A primeira entrada válida cria a sacola.

2. Peça a ada para enviar a primeira carta:

   postbag --bag default send @bob "Review my last commit. Reply with the top three findings."
   

   Se aceito, bob recebe: "Carta 1 de @ada para @bob via postbag (sacola default).", o corpo e as instruções de resposta: use postbag_send se as ferramentas MCP estiverem disponíveis, ou postbag --bag default send @ada - com a resposta no stdin. O rodapé pede respostas que avancem a tarefa e desencoraja agradecimentos de cortesia e verificações de entrega não solicitadas.

3. Leia a sacola de qualquer lugar com postbag --bag default read. Sua primeira linha nomeia a sacola, seus pares registrados e sua contagem de cartas registradas.

4. Para enviar uma carta que não pede resposta, use postbag --bag default send --final @bob "The review is complete.". Seu rodapé diz para não responder a essa carta, mesmo que seu corpo peça uma. Isso é orientação ao destinatário. Não fecha a sacola nem impede um envio posterior iniciado deliberadamente.

5. Para parar de participar desta sacola, peça à sessão para executar postbag --bag default leave, ou chame postbag_leave com bag="default". Isso libera seu nome sem encerrar a sessão ou excluir o histórico. Sua porta não pode mais enviar ou ser endereçada nessa sacola até que ela entre novamente. Cartas na fila e um envio que já segura o bloqueio da sacola ainda podem chegar. Reentre somente quando você deliberadamente pedir à sessão para retomar.

Se você pretende retomar a participação após um reinício, reentre na mesma sacola com o mesmo nome. Uma resposta alcança quem quer que segure o nome quando ela é executada, e o próximo send de uma porta deslocada recusa.

Sacolas

Uma sacola é um livro-razão, e tem um nome. default é ~/.postbag/ledger.jsonl. Para uma segunda conversa, cada sessão entra em outra sacola com o mesmo sinalizador, postbag --bag acceptance join claude ada e postbag --bag acceptance join claude bob, e ada envia com postbag --bag acceptance send @bob "...".

--bag vai antes do verbo e aceita um nome, mantido em ~/.postbag/bags/<name>.jsonl, ou um caminho absoluto de caracteres imprimíveis. join cria uma sacola default, nomeada ou selecionada por caminho ausente. send, leave e read recusam uma sacola ausente sem criar arquivos ou diretórios. Uma entrada recusada por seus argumentos ou identidade também não cria nada. Uma vez que a criação começa, uma falha de I/O pode deixar um diretório ou arquivo parcial para inspeção. As saídas identificam suas sacolas, e todo comando dentro de uma carta ou uma recusa carrega --bag, --bag default incluído, para que uma resposta caia onde a carta veio, independentemente do que o shell do destinatário tenha definido. Sem --bag, POSTBAG_LEDGER seleciona um livro-razão por caminho.

Execute postbag bags para uma contagem de caminhos encontrados, contagens de cartas registradas, horários da última carta e nomes registrados com fornecedores. Ele lista sacolas default, nomeadas e personalizadas selecionadas. Caminhos externos não selecionados são omitidos. Sacolas ocupadas ou ilegíveis estão indisponíveis. O resumo conta sacolas com cartas, sacolas sem cartas, e sacolas indisponíveis. Nomes registrados não implicam sessões ativas. Terminais se adaptam à largura e classificam sacolas pela última carta, com horários locais breves. Pipes mantêm a tabela simples e timestamps ISO completos.

postbag bags --resume adiciona comandos de retomada do Claude para conversas registradas em join, com um lembrete para IDs ausentes. Reentre após /clear ou trocar de conversas. Retomar precisa de histórico salvo e abre um novo processo, não o terminal antigo.

Como funciona

join escreve a porta da sessão no livro-razão sob um nome: o socket de mensagens e token do Claude Code, ou o id de thread do Codex. send segura um bloqueio de arquivo enquanto bate nessa porta e anexa a carta. Envios concluídos recebem números de registro distintos. Números de carta contam todas as cartas registradas na sacola. Números de registro também contam entradas, saídas e linhas históricas de open. CLI read N retorna os últimos N registros. MCP before e next_before endereçam números de registro imutáveis. Linhas antigas de open mantêm seus limites registrados como histórico e não controlam mais o envio. Antes de usar leave, atualize todos os leitores da sacola para 2.1 ou posterior e reconecte seus servidores MCP. Uma vez que uma saída é registrada, leitores 2.0 recusam essa sacola. Registros mais antigos não precisam de migração. Excluir linhas de saída não é um reparo porque restauraria registros retirados. Duas sessões são o uso suportado, três ou mais é experimental. Uma sacola é um livro-razão, o único estado. Sem daemon de entrega, polling, hooks ou índice de sacola. O processo MCP opcional é iniciado por seu host e usa as mesmas operações CLI em workers isolados. CONCEPT.md é a especificação.

Testes

Para uma execução completa de testes de desenvolvimento, instale ambas as dependências de teste e o extra MCP:

python -m pip install -e '.[dev,mcp]'
python -m pytest -q

Sem o extra mcp, os testes de wire são pulados. Testes usam fixtures privadas e portas nativas falsas. Veja Contribuindo.

Segurança e limites

• Um livro-razão contém todo token de sessão do Claude e toda carta em sua sacola. Novos arquivos usam 0600 e novos diretórios de estado 0700. Modos de arquivo existentes são preservados. Mutações recusam arquivos que concedem acesso de grupo ou outro ou não têm permissões de leitura e escrita do proprietário. read e bags ocultam credenciais de porta. Mantenha arquivos brutos fora de git e logs.
• Uma carta aceita é um turno de usuário. Confie em ambas as sessões com a tarefa. o postbag em si não envia nada para fora da máquina. Sessões de fornecedores encaminham a carta para seus serviços de modelo como qualquer prompt.
• Um nome é um endereço, não autenticação, e assim também é uma sacola. Roteamento do remetente usa as variáveis de sessão do fornecedor ou metadados de host confiáveis. Outro processo rodando como o mesmo usuário do SO pode fornecer esses campos.
• A política de entrada do Claude pode segurar ou recusar uma carta, incluindo em sessões de bypass de permissões. Envios CLI precisam de permissão para escrever o livro-razão e contatar o destinatário. Ferramentas MCP rodam com as permissões do processo do servidor, fora do sandbox de comandos. Use aprovações de ferramentas do host para consentimento por carta.
• Sair remove um registro em uma sacola. Não revoga a caixa de entrada nativa ou registros em outras sacolas. Subagentes do Claude que compartilham uma caixa de entrada compartilham um par, então um subagente saindo retira o nome do pai também.
• O Postbag não tem limite de cartas ou limite de taxa. O rodapé e --final são instruções de modelo, não proteção contra loops ou injeção de prompt. Fechar um cliente Codex não revoga a fila do thread salvo. Tornar um livro-razão não gravável impede novas aberturas de escrita. Mutações também verificam o modo após tomar o bloqueio, mas uma operação além dessa verificação pode terminar. Acesso de leitura pode permanecer, e cartas na fila não são recolhidas. Limites de profundidade de corpo, página e resultado do MCP permanecem, assim como timeouts nativos.
• "Entregue" significa submetido pela porta, não aceito ou lido. o postbag não espera por avisos de entrega nem tenta novamente. Uma falha antes de registrar deixa uma carta submetida em dúvida. Timeouts e comandos nativos falhos também podem deixar a submissão incerta. Verifique tanto a sacola quanto o destinatário antes de enviar novamente. Um registro ausente no livro-razão não é prova de entrega falha.

o postbag é uma pequena ponte para duas sessões existentes. Ferramentas que fazem mais · Conceito · Segurança · Changelog · Contribuindo · MIT