postbag

Cinco herramientas MCP y una CLI. Postbag no añade demonio de entrega, sondeos, hooks ni retransmisión remota. Transporta texto y registra las cartas enviadas. Los agentes y sus anfitriones deciden cuándo responder y cuándo detenerse. El código y otros productos de trabajo permanecen en tu repositorio.

Comandos CLI reales con bandejas de entrada falsas y un hogar temporal. Esta es una demostración local, no una grabación de agentes en vivo. Fuente de la demostración.

Consulta las instrucciones de instalación del agente.

Instalación

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

Python 3.10 o posterior, en macOS o Linux. Usa pipx install postbag solo para la CLI, que utiliza únicamente la biblioteca estándar. Actualiza las instalaciones de CLI y MCP de ambos pares juntas y reconecta sus servidores MCP. Las bolsas existentes no necesitan migración. Una vez que una bolsa contiene un registro de salida, todos sus lectores necesitan 2.1 o posterior. Consulta los detalles de migración.

Cada proveedor en uso trae su propia puerta. Una sesión de Claude Code exporta CLAUDE_CODE_MESSAGING_SOCKET y CLAUDE_CODE_MESSAGING_TOKEN a los comandos que ejecuta. Una sesión de Codex exporta CODEX_THREAD_ID (las versiones anteriores usan CODEX_SESSION_ID) y tiene un binario codex con el comando queue (0.149 o posterior). Configura POSTBAG_CODEX si no está en la aplicación ChatGPT o en PATH. Dos sesiones de Claude no necesitan binario de Codex, dos sesiones de Codex no necesitan socket de Claude.

Herramientas MCP

La interfaz MCP opcional permite a los agentes llamar a postbag_join, postbag_leave, postbag_send, postbag_read y postbag_bags directamente. La identidad del remitente proviene del anfitrión. El libro mayor y la entrega nativa son los mismos que en la CLI. Unirse crea una bolsa faltante. No hay presupuesto de cartas ni comando solo para humanos.

Instala las herramientas opcionales con:

pipx install 'postbag[mcp]'

O deja que uv ejecute el paquete fijado en un entorno aislado:

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

Esto inicia un servidor MCP stdio para que un anfitrión lo gestione. Espera entrada de protocolo, en lugar de abrir un prompt de terminal interactivo. postbag mcp y postbag-mcp sirven las mismas cinco herramientas. El lanzador no toma --bag ni argumentos operativos. Cada llamada de herramienta selecciona su propia bolsa.

Registra la ruta absoluta a postbag-mcp como un servidor MCP stdio local en cada anfitrión. Configuración, actualizaciones y compatibilidad. El SDK de MCP solo se requiere para esta interfaz.

Los pares compatibles son sesiones existentes de Claude Code y Codex. Un cliente MCP genérico puede inspeccionar bolsas, pero registrar y enviar requieren la identidad de sesión nativa de un anfitrión compatible. Instala Postbag en la misma máquina que ambas sesiones. La verificación de Docker de un directorio puede inspeccionar el catálogo de herramientas sin proporcionar acceso a esas sesiones.

El candidato 2.2 instalado c56d92d pasó la aceptación nativa a través de postbag mcp en macOS con Claude Code 2.1.287 y Codex 0.159.2. Cinco cartas fueron observadas en sus destinatarios, incluidas respuestas en ambas direcciones. Salir bloqueó un envío posterior, la reincorporación deliberada restauró la entrega, y ninguna respuesta siguió a una carta final durante una ventana de observación de 30.0992 segundos. Consulta evidencia y límites del lanzador.

El candidato 2.0 instalado 8b87b4f pasó la aceptación nativa en macOS con Claude Code 2.1.286 y Codex 0.158.0-alpha.2.1. La verificación observó recepción bidireccional, sin respuesta de Postbag durante 30.0668 segundos después de una carta final, y un viaje de ida y vuelta ordinario iniciado deliberadamente más tarde. Esta observación no garantiza que otras conversaciones de modelos se detengan. Consulta evidencia y límites del candidato.

Las verificaciones históricas de entrega nativa 1.x se ejecutaron en macOS con Claude Code 2.1.285 y Codex 0.157.1 / escritorio 0.158.0-alpha.2.1, incluido el paquete MCP 1.3.0 instalado, descubrimiento de servidor predeterminado, recepción bidireccional y rechazo por presupuesto agotado. Las verificaciones 1.4 también se conservan en compatibilidad nativa. La entrega nativa en Linux no está verificada. Windows no es compatible.

Inicio rápido

1. Abre dos sesiones en la misma máquina. Pide a cada una que se una con un nombre: postbag --bag default join claude ada y postbag --bag default join claude bob, o postbag --bag default join codex bob para Codex. Los pares del mismo proveedor necesitan nombres distintos. La primera unión válida crea la bolsa.

2. Pide a ada que envíe la primera carta:

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

   Si se acepta, bob recibe: "Carta 1 de @ada a @bob vía postbag (bolsa default).", el cuerpo y las instrucciones de respuesta: usa postbag_send si las herramientas MCP están disponibles, o postbag --bag default send @ada - con la respuesta en stdin. El pie de página pide respuestas que avancen la tarea y desaconseja los acuses de cortesía y las verificaciones de entrega no solicitadas.

3. Lee la bolsa desde cualquier lugar con postbag --bag default read. Su primera línea nombra la bolsa, sus pares registrados y su recuento de cartas registradas.

4. Para enviar una carta que no solicita respuesta, usa postbag --bag default send --final @bob "The review is complete.". Su pie de página dice que no se responda a esa carta, incluso si su cuerpo lo solicita. Esto es una guía para el destinatario. No cierra la bolsa ni impide un envío posterior iniciado deliberadamente.

5. Para dejar de participar en esta bolsa, pide a la sesión que ejecute postbag --bag default leave, o llama a postbag_leave con bag="default". Esto libera su nombre sin terminar la sesión ni eliminar el historial. Su puerta ya no puede enviar ni ser direccionada en esa bolsa hasta que se una de nuevo. Las cartas en cola y un envío que ya tiene el bloqueo de la bolsa aún pueden llegar. Reincorpórate solo cuando pidas deliberadamente a la sesión que reanude.

Si tienes la intención de reanudar la participación después de un reinicio, vuelve a unirte a la misma bolsa con el mismo nombre. Una respuesta llega a quien tenga el nombre cuando se ejecute, y la siguiente send de una puerta desplazada se rechaza.

Bolsas

Una bolsa es un libro mayor, y tiene un nombre. default es ~/.postbag/ledger.jsonl. Para una segunda conversación, cada sesión se une a otra bolsa con la misma bandera, postbag --bag acceptance join claude ada y postbag --bag acceptance join claude bob, y ada envía con postbag --bag acceptance send @bob "...".

--bag va antes del verbo y toma un nombre, guardado en ~/.postbag/bags/<name>.jsonl, o una ruta absoluta de caracteres imprimibles. join crea una bolsa faltante predeterminada, nombrada o seleccionada por ruta. send, leave y read rechazan una bolsa faltante sin crear archivos ni directorios. Una unión rechazada por sus argumentos o identidad tampoco crea nada. Una vez que la creación comienza, una falla de E/S puede dejar un directorio o un archivo parcial para inspección. Las salidas identifican sus bolsas, y cada comando dentro de una carta o un rechazo lleva --bag, --bag default incluido, para que una respuesta aterrice donde vino la carta, independientemente de lo que el shell del destinatario tenga configurado. Sin --bag, POSTBAG_LEDGER selecciona un libro mayor por ruta.

Ejecuta postbag bags para un recuento de rutas encontradas, recuentos de cartas registradas, horas de la última carta y nombres registrados con proveedores. Enumera bolsas predeterminadas, nombradas y personalizadas seleccionadas. Las rutas externas no seleccionadas se omiten. Las bolsas ocupadas o ilegibles no están disponibles. El resumen cuenta bolsas con cartas, bolsas sin cartas y bolsas no disponibles. Los nombres registrados no implican sesiones en vivo. Los terminales se adaptan al ancho y ordenan las bolsas por última carta, con horas locales breves. Las tuberías mantienen la tabla simple y las marcas de tiempo ISO completas.

postbag bags --resume añade comandos de reanudación de Claude para conversaciones registradas en join, con un recordatorio para IDs faltantes. Reincorpórate después de /clear o de cambiar conversaciones. Reanudar necesita historial guardado y abre un nuevo proceso, no el terminal anterior.

Cómo funciona

join escribe la puerta de la sesión en el libro mayor bajo un nombre: el socket de mensajería y token de Claude Code, o el id de hilo de Codex. send mantiene un bloqueo de archivo mientras toca esa puerta y añade la carta. Los envíos completados obtienen números de registro distintos. Los números de carta cuentan todas las cartas registradas en la bolsa. Los números de registro también cuentan uniones, salidas y filas históricas de open. La CLI read N devuelve los últimos N registros. MCP before y next_before direccionan números de registro inmutables. Las filas antiguas de open mantienen sus límites registrados como historial y ya no controlan el envío. Antes de usar leave, actualiza todos los lectores de la bolsa a 2.1 o posterior y reconecta sus servidores MCP. Una vez que se registra una salida, los lectores 2.0 rechazan esa bolsa. Los registros antiguos no necesitan migración. Eliminar filas de salida no es una reparación porque restauraría registros retirados. Dos sesiones son el uso compatible; tres o más es experimental. Una bolsa es un libro mayor, el único estado. Sin demonio de entrega, sondeos, hooks ni índice de bolsas. El proceso MCP opcional es iniciado por su anfitrión y usa las mismas operaciones CLI en trabajadores aislados. CONCEPT.md es la especificación.

Pruebas

Para una ejecución completa de pruebas de desarrollo, instala ambas dependencias de prueba y el extra MCP:

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

Sin el extra mcp, las pruebas de cable se omiten. Las pruebas usan fixtures privados y puertas nativas falsas. Consulta Contribuir.

Seguridad y límites

• Un libro mayor contiene cada token de sesión de Claude y cada carta en su bolsa. Los archivos nuevos usan 0600 y los directorios de estado nuevos 0700. Los modos de archivo existentes se conservan. Las mutaciones rechazan archivos que otorgan acceso de grupo u otro o que carecen de permisos de lectura y escritura del propietario. read y bags ocultan credenciales de puerta. Mantén los archivos sin procesar fuera de git y registros.
• Una carta aceptada es un turno de usuario. Confía en ambas sesiones con la tarea. postbag en sí no envía nada fuera de la máquina. Las sesiones del proveedor reenvían la carta a sus servicios de modelo como cualquier prompt.
• Un nombre es una dirección, no autenticación, y también lo es una bolsa. El enrutamiento del remitente usa las variables de sesión del proveedor o metadatos confiables del anfitrión. Otro proceso que se ejecuta como el mismo usuario del SO puede proporcionar esos campos.
• La política de entrada de Claude puede retener o rechazar una carta, incluso en sesiones de permisos omitidos. Los envíos CLI necesitan permiso para escribir el libro mayor y contactar al destinatario. Las herramientas MCP se ejecutan con los permisos del proceso del servidor, fuera del sandbox de comandos. Usa las aprobaciones de herramientas del anfitrión para el consentimiento por carta.
• Salir elimina un registro en una bolsa. No revoca la bandeja de entrada nativa ni los registros en otras bolsas. Los subagentes de Claude que comparten una bandeja de entrada comparten un par, por lo que la salida de un subagente también retira el nombre del padre.
• Postbag no tiene límite de cartas ni límite de velocidad. El pie de página y --final son instrucciones del modelo, no protección contra bucles o inyección de prompts. Cerrar un cliente de Codex no revoca la cola de su hilo guardado. Hacer ilegible un libro mayor impide nuevas aperturas de escritura. Las mutaciones también verifican el modo después de tomar el bloqueo, pero una operación más allá de esa verificación puede terminar. El acceso de lectura puede permanecer, y las cartas en cola no se recuperan. Los límites de profundidad del cuerpo, página y resultado de MCP permanecen, así como los tiempos de espera nativos.
• "Entregado" significa enviado a través de la puerta, no aceptado o leído. postbag no espera avisos de entrega ni reintenta. Un bloqueo antes de registrar deja una carta enviada en duda. Los tiempos de espera y los comandos nativos fallidos también pueden dejar el envío incierto. Verifica tanto la bolsa como el destinatario antes de enviar de nuevo. Un registro ausente en el libro mayor no es prueba de entrega fallida.

postbag es un pequeño puente para dos sesiones existentes. Herramientas que hacen más · Concepto · Seguridad · Registro de cambios · Contribuir · MIT