postbag — Claude Code MCP server: letters between agents
A local MCP server that lets Codex and Claude exchange letters. A reply shows up as a new turn in the other session, so nothing gets pasted between windows.
claude mcp add --env POSTBAG_CODEX=<POSTBAG_CODEX> --transport stdio postbag -- uvx postbagWhat postbag does
postbag links two sessions running on one machine: one in Codex, one in Claude. An agent addresses a letter by name, and it lands in the peer session as a fresh turn, arriving through that session's own input. There is no delivery daemon, no polling and no hooks.
Five tools do the work. postbag_join registers a session under a name inside a bag, postbag_send posts a letter, postbag_read pages the history, postbag_bags lists bags, postbag_leave withdraws the session. A bag is a named conversation with a shared local log both agents can read. Marking a letter final means no answer is expected.
Check your setup first: Python 3.10 or newer is required, along with a recent Codex CLI that has codex queue, and both sessions must run the same postbag version. Delivery is tested on macOS. Ledgers in ~/.postbag/ carry Claude inbox tokens, and new files are written with mode 0600 — keep them out of commits and don't hand them around. Delivery into a peer session is still a matter of trust: the server only asks the recipient to stay inside the human's existing authorization.
What it helps with
- have Codex review a diff before you commit
- split a task so one agent writes tests and the other the code
- get a second read on a bug one agent is stuck on
- pass requests between sessions without copying text
- keep one shared log of two agents talking
Example prompts for the agent
- Join postbag bag "review" as codex.
- Send a final letter to the "review" bag with the findings.
How to install postbag
Platform CLI
claude mcp add --env POSTBAG_CODEX=<POSTBAG_CODEX> --transport stdio postbag -- uvx postbagReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from postbag <command>
Platform CLI
codex mcp add postbag --env POSTBAG_CODEX=<POSTBAG_CODEX> -- uvx postbagReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from postbag <command>
Config file
{
"mcpServers": {
"postbag": {
"command": "uvx",
"args": [
"postbag"
],
"env": {
"POSTBAG_CODEX": "<POSTBAG_CODEX>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from postbag <command>
Config file
{
"servers": {
"postbag": {
"type": "stdio",
"command": "uvx",
"args": [
"postbag"
],
"env": {
"POSTBAG_CODEX": "<POSTBAG_CODEX>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from postbag <command>
Platform CLI
gemini mcp add -e POSTBAG_CODEX=<POSTBAG_CODEX> postbag uvx postbagReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from postbag <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about postbag
How do I install postbag in Claude Code?
Run pipx install 'postbag[mcp]', then claude mcp add --scope user postbag -- "$(command -v postbag-mcp)". Start a new session and run /mcp; postbag should list five tools.
What does postbag do?
It lets two local sessions, Codex and Claude, send each other letters. A letter arrives in the peer session as a new turn, and the bag keeps a shared history both sides can page through.
What does postbag need to run?
Python 3.10 or newer, Claude, and a recent Codex CLI with codex queue. Both sessions run on the same machine with the same postbag version.
