Postbag
Let Claude Code and Codex write letters to each other through their own native input, without copying text between windows.
- Source repo
- parasxos/postbag
- Stars
- ★ 11
- Last updated
- 23d ago
- License
- MIT
- Primary language
- Python
- FA score
- 60/100 · Some gaps
At a glance
- Works with
- Portable with changesCodex · Claude Code
- You'll need
- Typical use
- A developer finishes a change in Claude Code and asks Codex to review the diff before committing.
- Main limitation
- Delivery is tested only on macOS; other operating systems are unverified.
- Source review
- 60/100 · Some gaps
What does this agent do, and when should you use it?
Postbag is a local MCP server that pairs two coding-agent sessions, Claude Code and Codex, inside a named "bag" and lets them exchange letters. After a single pipx install it registers postbag-mcp with both apps, giving each session five tools: postbag_join, postbag_send, postbag_read, postbag_bags and postbag_leave. An accepted letter arrives as a new turn through the recipient's own native input, with no delivery daemon, polling or hooks. Each bag keeps a local log that either side can page through with postbag_read. The core is Python standard library with CLI and MCP entry points. Delivery is tested on macOS, and both sessions must run the same postbag version on one machine.
An agent calls postbag_join to register its session under a name in a bag, creating the bag if needed. It then calls postbag_send to write a letter to a named peer; final: true marks the closing letter that asks for no reply. Every letter ends with instructions on how to reply, or a statement that no reply is wanted, so the recipient needs no extra prompt. The letter is delivered into the other session through its own input and becomes a new turn there. A successful send confirms submission and recording only — not that the recipient accepted, read or acted on it. postbag_read pages through bag history, postbag_bags lists local bags with letter counts and registered names, and postbag_leave withdraws the session while keeping history. Ledgers live under ~/.postbag/, hold Claude Code inbox tokens, and new files use mode 0600.
- A developer finishes a change in Claude Code and asks Codex to review the diff before committing.
- Splitting work so Codex writes tests while Claude Code writes the implementation, then comparing notes by letter.
- An agent stuck on a bug asks the other for a fresh read of the same code.
- Someone running both sessions in one repository who wants to stop copy-pasting context between terminal windows.
- A team that wants a local, reviewable record of a two-agent discussion, pageable later with
postbag_read.
How do you install or deploy this agent?
Requires Python 3.10 or later, Claude Code, and a recent Codex CLI with codex queue. Run both sessions on one machine with the same postbag version.
pipx install 'postbag[mcp]'
claude mcp add --scope user postbag -- "$(command -v postbag-mcp)"
codex mcp add postbag -- "$(command -v postbag-mcp)"Start a new session in each app and run /mcp; postbag should list five tools. For uvx and other setups, see the repository's MCP setup doc.
How do you use this agent?
Open Codex and Claude Code in the same repository so both see the same code.
In Codex:
Join postbag bag "review" as codex.In Claude Code:
Join postbag bag "review" as claude, then ask codex to review my last commit.Codex joins first so Claude Code has someone to write to. Approve the postbag tools when asked. The request arrives in Codex as a new turn, its reply lands back in Claude Code the same way, and either side can close with a final letter.
What are this agent's strengths and limitations?
- Delivery uses each agent's own native input, so there is no extra daemon, polling loop or hook to run.
- Python standard library core keeps the dependency surface small; install is one pipx command.
- Ships both CLI and MCP entry points with a deliberately small five-tool interface.
- Letters carry their own reply instructions or a no-reply marker, avoiding setup prompts.
- A shared per-bag log makes the exchange auditable and pageable via
postbag_read.
- Delivery is tested only on macOS; other operating systems are unverified.
- Depends on Codex CLI's
codex queuefeature and a recent Codex CLI version. - Both sessions must run on the same machine with the same postbag version, so no remote peers.
- Send confirmation does not prove the peer received, read or acted on the letter.
- Ledgers contain Claude Code inbox tokens, so you must keep them out of commits and shares.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Postbag This agent | 60 · Some gaps | — | ★ 11 | 23d ago | Python | Codex · Claude Code |
| AgentBridge | 61 · Some gaps | CLIFree + model costs | ★ 414 | today | TypeScript | Codex · Claude Code |
| RepoBrain – Repo Intelligence Engine | 49 · Major gaps | Agent plugin / skillFree + model costs | ★ 1.4k | 11d ago | Python | Codex · Claude Code |
| SkillKit — Package Manager for AI Agent Skills | 40 · Major gaps | CLIFree + model costs | ★ 1.6k | 4mo ago | TypeScript | ChatGPT · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Least privilege: stdlib-only core, no daemon, writes confined to ~/.postbag and explicit paths, new files 0600 and dirs 0700, refuses non-regular files and unprintable paths — reasonable but still injects turns into peer sessions. User confirmation: README states there is no letter limit and hosts must configure confirmation before each postbag_send; no default confirmation, so 1. Data-flow transparency: README and tests clearly describe native-input delivery and that receipts do not prove read/acceptance. Sensitive data: README notes ledgers hold Claude Code inbox tokens, 0600, never commit; tests cover modes, but tokens are stored in plaintext without encryption — deducted. Dependency security: zero core deps, optional mcp pinned mcp>=2.2,<3, CI actions pinned by SHA. External effects: sending injects a turn into another session, an irreversible side effect only bounded by final and guidance. Rollback: no mechanism to retract a delivered letter; history is retained only — deducted. Source attribution: MIT and author clear, but publisher is unverified (unknown, not suspicious) — 1.
Self-consistency: tests cover selector precedence, no implicit bag creation, creation races, legacy ledger compatibility; behavior matches docs. Dependency availability: requires-python>=3.10, no third-party core deps, optional mcp, CI matrix across versions and OSes. Failure messages: errors consistently name the bag, give a recovery command and 'stop and ask the human', asserted verbatim in tests — 3.
Audience and scenarios: targets developers doing cross Claude Code/Codex review; scenarios clear. Capability boundaries: README states delivery does not prove read/acceptance and model guidance is not a security boundary. Trigger precision: tool table and join/send/read semantics clear, final semantics tested. Environment fit: README says delivery tested only on macOS and requires codex queue and specific CLI versions; cross-platform evidence limited — deducted.
Information architecture: README well structured with install, quick start, tools, security. Install notes: concrete pipx and claude/codex mcp add commands plus llms-install.md. Naming stability: tool names and CLI verbs stable and tested. Examples and FAQ: quick start and demo GIF but no dedicated FAQ — deducted. Known limitations: README states no letter limit, delivery not guaranteed read, macOS-only testing. License: full MIT text consistent with pyproject — 3. Versioning/changelog: CHANGELOG referenced and release workflow validates tag/version, but changelog body not in evidence — 2. Maintenance responsibility: single author, unverified publisher, no governance — deducted.
Output usability: receipts are explicit with bag and unconfirmed note; read paginates and marks final. Marginal value: solves cross-session copy-paste pain but requires both agents online. Cost benefit: zero deps, lightweight pipx install, but needs dual sessions and manual confirmation config — moderate.
Claim traceability: README claims map to tests and CI steps (0600 modes, final semantics). Cross-source corroboration: README, pyproject, CI and tests agree on version and behavior. Fact/inference separation: README distinguishes submission success from recipient read, no overclaiming. Publisher identity and live PyPI state cannot be statically confirmed; overall confidence low.
- No default per-send confirmation and no letter limit, so many cross-session injections are possible; configure host confirmation.
- Ledgers store Claude Code inbox tokens in plaintext; keep 0600 and never commit or share.
- Successful delivery does not mean the peer read or acted; do not infer task completion.
- Delivery tested only on macOS; Linux and specific codex queue version compatibility not fully verified.
- Publisher identity is unverified by FollowAgents; verify source and PyPI package before installing.
FAQ
Does Postbag cost anything?
Can the two agents run on different machines?
Should I treat a successful send as a delivered reply?
Can I limit how many letters an agent sends?
postbag_send call. The in-letter request to stay within the human's authorization is model guidance, not a security boundary.