postbag

## postbagとは postbagは、同一マシン上で動作する2つのAIコーディングエージェントセッションが、互いに手紙を書き合えるようにする小さなブリッジです。セッションは同一ベンダーでも異なるベンダーでも構いません（例：Claude CodeとCodex、またはClaude Code同士、Codex同士）。各手紙は受信側ベンダー独自のウェイクアップメカニズム（「ドア」）を通じて配信され、単一の共有レジャーに追加され、人間が設定した手紙の予算（予算枠）からカウントされます。 READMEで提案されている典型的な用途には、一方のエージェントに他方のdiffをレビューさせる、タスクを2つのエージェントに分割して手紙でインターフェースを合意させる、あるいはコンテキストを手動でコピー＆ペーストせずにセカンドオピニオンを得るなどが含まれます。READMEでは、役割分担を「テキストはpostbagで、コードはgitで移動する」と定義しています。 ## 仕組み - `join`: セッションのドアを名前付きでレジャーに登録します。Claude Codeの場合はセッションごとのメッセージングソケットとトークン、Codexの場合はスレッドIDが使用されます。 - `send`: 登録されたドア（ソケットまたは`codex queue`）をノックし、ファイルロックを用いて手紙を追記します。これにより、同時に送信された手紙に個別の番号が割り振られ、予算が共有されます。 - `open`: セッション外の通常のターミナルから次のやり取りを開始します。手紙はやり取りの中で番号付けされ、予算はバッグ内の全員で共有されます。`--limit`を指定しない場合、1つのやり取りは12通の手紙まで保持されます。 - `read`: 現在バッグ内にいる名前、開いているやり取り、およびレコードを表示します。 - `~/.postbag/ledger.jsonl`にあるレジャーが唯一の状態保持先です。デーモン、ポーリング、フック、サーバー、設定ファイルは一切不要です。両方のセッションとターミナルで同じ`POSTBAG_LEDGER`を設定することで、別のバッグを作成できます。 受信側は、番号付きの手紙、残り回数、本文、およびそれに回答するための唯一のコマンド（標準入力に返信内容を含む`send`）を受け取って起動します。やり取りの最後の手紙には返信しないよう指示があり、その後の送信は拒否され、エージェントに停止して人間に尋ねるよう伝えます。 ## 要件 Python 3.10以降（標準ライブラリのみ）。`pipx install postbag`でインストール可能です。Claude Codeセッションには、`CLAUDE_CODE_MESSAGING_SOCKET`および`CLAUDE_CODE_MESSAGING_TOKEN`を通じてセッションごとのメッセージングソケットをエクスポートする必要があります。Codexセッションには、Codex 0.149で導入された`queue`コマンド、エクスポートされた`CODEX_SESSION_ID`、および動作する`codex queue --help`が必要です。`POSTBAG_CODEX`で非標準のバイナリを指定することも可能です。2つのClaudeセッションにはCodexバイナリは不要であり、2つのCodexセッションにはClaudeソケットは不要です。 ## 検証とプラットフォームサポート READMEではmacOSでの動作検証が報告されています。バージョン1.0.2ではClaude Code 2.1.263とChatGPTデスクトップアプリのCodex 0.153.4を使用し、バージョン1.1.0では2つの本物のClaude Code 2.1.263セッション（双方向のやり取りと予算切れによる拒否を含む）で検証されています。LinuxはCIをパスしていますが、実機での配信は未検証とされており、Windowsはサポートされていません。 ## 制限事項とセキュリティ上の注意 - レジャーには手紙だけでなく、すべてのClaudeセッショントークンが保存されます。書き込み時はファイル権限を`0600`、新しい状態ディレクトリを`0700`に保持します（既存のカスタムディレクトリはそのまま）。`read`はドアのフィールドを隠しますが、`cat`は隠さないため、生ファイルはgit、ログ、スクリーンショットに含めないようにしてください。 - 手紙は受信セッションにおけるユーザーのターンとなるため、両方のセッションがタスクを信頼できるものである必要があります。postbag自体はマシン外に何も送信しませんが、ベンダーセッションは通常の手順と同様に手紙をモデルサービスに転送します。 - 名前はアドレスであり、認証ではありません。`open`はセッション内での実行を拒否します。これらのチェックはベンダーのセッション変数を読み取っており、役割の混同を防ぐガードレールであり、同一ユーザーとして動作する別のプロセスからの保護ではありません。 - テストされたバージョンでは、バイパス権限がある場合にClaudeへの無人配信が確認されました。他のモードでは承認待ちになる場合があります。Codexはレジャーへの書き込み権限とClaudeソケットへの接続権限が必要です。 - 「配信済み」とはドアを通じて送信されたことを意味し、既読であることを意味しません。送信と記録の間にタイムアウトやクラッシュが発生した場合、手紙の状態は不明となり、確認応答や再試行機能はありません。 ## 範囲と互換性 サポートされている構成は2セッションです。3つ以上のセッションは実験的とされており、`read`でその旨が表示され、各手紙に登録名がリストされます。バージョン1.0で作成されたレジャーは書き換えなしで読み込み可能で、レガシーなベンダーピアは`@claude`および`@codex`として読み込まれます。1.0セッションと1.1セッションの混在はサポートされていません。1.0の`send`は単純な`claude`または`codex`しか受け付けず、1.1の手紙に含まれる返信コマンドを実行できないためです。両方のセッションをアップグレードし、再度`join`させる必要があります。再起動後、セッションは以前保持していた名前で再度`join`する必要があり、返信コマンドは実行時にその名前を保持している相手に届きます。 リポジトリはMITライセンスで、`CONCEPT.md`形式のコンセプトドキュメント、変更履歴、貢献ガイド、および同分野の他のツールをリストしたリサーチドキュメントが含まれています。