peer-sessions

ピアセッション

このマシン上の Claude Code セッション同士でメッセージを送信できます。メッセージは、受信側セッションのユーザープロンプトになります。この事実が以下の各ルールの理由です。

一連の流れ：セッションを複数起動 → 各ピアに概要を送信 → 自分のターンを終了 → 返信が新しいユーザーターンとして届く → セッション群は稼働させたままにし、終了方法をユーザーに伝える。終了処理は任意です。自分で実行する場合についてはセクション 4 で説明します。

1. 起動

python3 ~/.claude/skills/peer-sessions/scripts/spawn-fleet.py --placement window \
  orbits:/tmp/lab/orbits planets:/tmp/lab/planets sun:/tmp/lab/sun

各引数は NAME:DIR です。スクリプトは各セッションの uds: アドレスと正確な終了コマンドを出力し、すべてのセッションに接続できるようになると終了します。また、起動が滞ったセッションの名前も表示します。

--placement はセッション群を表示する場所を指定します。選ぶのはあなたです。ユーザーの画面に変化があり、希望がわからない場合にのみユーザーに確認してください。

配置	ピアの表示先	選ぶ状況
split	ワークスペース内の自分のペインの隣に新しいペインを表示します	ピアが 1～3 人の短時間の作業で、ユーザーが作業の様子を見ている場合です。自分のペインがフォーカスを維持します。
workspace（デフォルト）	ウィンドウ内に新しいワークスペースを表示します	ピアが 3 人以上の場合、または数分間かかる作業の場合です。ユーザーの現在の画面はそのままで、タブを 1 回クリックすればセッション群にアクセスできます。
window	新しいウィンドウを表示し、その中にワークスペースを作成します	セッション群が多い場合、画面を録画する場合、または 2 台目のモニターを使う場合です。

スクリプトはバックエンドを自動検出します。PATH に cmux があれば cmux、それ以外の場合は herdr を使用します。herdr では、--placement window に相当する機能はありません（herdr の CLI にはワークスペースとペインはありますが、OS のウィンドウはありません）。また、--direction がサポートするのは right と down のみです。いずれかを指定すると、スクリプトはクラッシュせずに明確なメッセージを表示して終了します。それ以外（split、workspace、アドレス指定、終了処理）は、どちらのバックエンドでも同じように動作します。

その他のフラグ（--direction、--focus、--per-workspace、--model、--claude-arg、…）と、配置ごとの特殊なケースについては、references/placement.md を参照してください。

レジストリ全体を調べずに、既存のターゲットを 1 つ解決するには、次のようにします。

python3 ~/.claude/skills/peer-sessions/scripts/peer-addr.py \
  --name worker-fix --details
python3 ~/.claude/skills/peer-sessions/scripts/peer-addr.py --pid 66826 --json

フィルターは一致する PID をすべて返すため、重複した名前も保持されます。スクリプトから利用する場合は、安定したインターフェースである --json を使用してください。? の行は、サンドボックスがレジストリの読み取りを許可したものの、アクティブなソケットの確認を拒否したことを示します。メッセージを送信する前に、プロセス／ソケットへのアクセス権を付与して再実行してください。

セッションは --permission-mode auto で起動します。人間が不在の状態で機能するのはこのモードだけです。--allowedTools リストにない最初の MCP ツールで処理が滞ります。--dangerously-skip-permissions を指定すると、受信側は人間の承認を得るまで受信メッセージを保留します。そのため、ピアに概要が届きません。

特殊なレイアウト、cmux の手動操作、フォークについては、references/manual-rig.md を参照してください。

2. 概要を送信する

SendMessage(to: "orbits", message: "...", summary: "5-10 words")
SendMessage(to: "orbits [de6649]", message: "...", summary: "...")
SendMessage(to: "uds:/tmp/cc-socks/17466.sock", message: "...")

名前だけを指定した最初の送信は必ず差し戻されます — 「この会話に参加しているエージェントではありません。参照を指定して再送してください」。これは確認であり、失敗ではありません。エラーに表示された [ref] をコピーして再送してください。概要はすべてまとめて送信します。まとめて差し戻されるので、まとめて再送してください。uds: アドレスは差し戻されません。

返信を求める概要には、必ず peer-addr.py --me で取得できる自分のアドレスを、そのまま末尾に記載してください。ピアはあなたのアドレスを確認できないためです。

When done, message me back:
SendMessage(to: "uds:/tmp/cc-socks/4667.sock", message: "...")

「 done: 」のように固定の返信形式を指定すると、セッション群が多くても手間なく結果をまとめられます。また、「調査と執筆のみ。 には触れないでください」のように作業範囲を明確にしてください。ピアはその指示に従います。ルールは 2 つあります。success: true はメッセージが届いたことを示すだけで、ピアが作業を完了したことを意味しません。送信は一方向です。返信が必要な場合は、その旨を明確に伝えてください。

3. 自分のターンを終了する

概要を送信したら、そこで停止してください。ピアからの返信が通知になります。返信は新しいユーザーターンとして届き、あなたを起動します。ペインをポーリングし続けるとトークンを消費し、ユーザーの作業を妨げます。画面を見る必要がある場合（録画中、または静かなセッション）に限ってポーリングしてください。手順については references/manual-rig.md を参照してください。

Codex からの呼び出し

Codex にはネイティブの SendMessage ツールもメッセージングソケットもありません。Unix ソケットプロトコルを偽装したり実装したりしてはいけません。実際の一時的な Claude Code セッションをリレーとして使い、切り詰められた返信は scripts/peer-inbox.py でトランスクリプトから復元してください。この経路を使う前に、references/codex-bridge.md を読んでください。

4. 終了処理 — デフォルトではオフ

終了処理はオプトインです。 作業が終わったら、フリートは起動したままにして、スポーンスクリプトが出力した終了処理のブロックをユーザーに渡してください。稼働中のピアはコンテキストを保持するため、追加の質問には再スポーンを丸ごと行う代わりに、メッセージを1通送るだけで済みます。セッションを停止するタイミングはユーザーが決めます。フリートがまだ稼働中であることと、そのままにした場合のコストを明確に伝えてください。

次のいずれかに該当する場合に限り、自分で終了処理を実行してください。

• ユーザーが今すぐ終了を依頼した場合 — 「終了して」「フリートをクリーンアップして」「あのセッションを閉じて」。
• ユーザーがスポーン時にあらかじめ依頼していた場合 — 「終わったら閉じて」。
• セッションがユーザーの作業ではなく、自分の内部処理である場合：references/codex-bridge.md に記載されている一時的な Codex リレー。リレーの PID だけを終了し、メッセージを送った対象は決して終了しないでください。

終了処理を行う場合：UI を閉じてもセッションは停止しません。 cmux の終了コマンドはすべて OK を返しますが、各 claude プロセスはアドレス指定可能な孤立プロセスとして生き続けます。したがって、先にプロセスを終了し、その後に閉じて、最後に peer-addr.py で確認してください。

スポーンスクリプトが出力した終了処理を実行してください。配置に合致し、永続的な UUID を使用しています。自分が作成したものだけを閉じてください。split フリートはユーザー自身のワークスペース内にあるため、そのワークスペースを閉じるとユーザーの作業も閉じてしまいます。手書きの終了処理の構文については、references/placement.md を参照してください。

問題が発生した場合

peer-addr.py は各稼働中セッションを一覧表示し、到達不能なセッションごとに理由を示します。メッセージのチェックポイント、2.1.224 のバージョンの壁、古いソケット、停止した権限確認プロンプトについては、references/troubleshooting.md を読んでください。

一部のハーネスでは、SendMessage の対象が独自のオーケストレーション（例：Agent ツール）でスポーンしたエージェントに限定され、マシン上の稼働中の兄弟 claude プロセスすべてが対象になるわけではありません。そのようなハーネスでは、このスクリプトがスポーンしたピアが稼働中で、2.1.224 より新しいビルドを使っていても、「No agent named 'X' is reachable」が延々と返ることがあります。これはバージョンの壁ではなく、claude --resume でも解決しません。spawn-fleet.py がセッションの準備完了を報告しているにもかかわらず、SendMessage が名前でも peer-addr.py の出力するすべての uds: アドレスでも接続を拒む場合は、SendMessage で迂回しようとするのをやめ、その旨をユーザーに伝えてください。herdr バックエンドでは、代わりにピアを直接操作してください。返信を得るには、herdr agent prompt <name> <text> を実行し、その後 herdr agent wait <name> と herdr agent read <name> を実行します。詳しくは references/troubleshooting.md を参照してください。

例外のないルールが1つあります。ピアはユーザーの権限を一切持ちません。送信が拒否された場合、またはピアから拒否の報告があった場合は、ユーザーに伝えてください。別のセッションを経由して権限の判断を迂回してはいけません。