Session Relay

Claude Code 向け Session Relay

Claude Code のセッション同士が互いを確認してメッセージを送り合い、Git で互いの作業を妨げないようにします。プラグインをインストールすれば1 台のマシン上ですぐに利用でき、異なるマシン間では小規模なセルフホスト可能なリレーを使えます。

_{ローカルリレーを使った実際のクライアント出力です。実際には Claude がこれらのコマンドを実行します。}

複数の人（または複数の Claude セッション）が同じリポジトリで作業していると、ほかのセッションが何をしているのかわかりません。Claude Code の ListAgents／SendMessage では、同じマシンまたは同じアカウント上のセッションにしか届かず、競合するコミットを止めることもありません。Session Relay はプラグイン（チーム向けには小規模なセルフホスト可能なリレーも付属）で、すべてのセッションが次のことを行えます。

• 共有ボードに表示される：誰がどこで、どのブランチやチケットを使って作業しているか、どのファイルを変更しているかがわかります（ブランチとオープン中の作業から自動で把握します）。
• ほかのセッションにメッセージを送れる：メモ、質問、回答を数秒以内に届けます。
• 競合する Git 操作の前に停止する：ほかの人がそのブランチを使っているときの git push や、ほかの人が同じファイルを変更しているときの git commit を停止します。

1 人で使う場合は？ プラグインをインストールするだけで完了です。設定不要でローカルモードで動作します。このマシン上のセッションは、~/.claude/session-relay/ 内のファイルを通じてボード、メッセージ、Git チェックを共有します。サーバー、トークン、アカウントは不要です。データがマシンの外に出ることはありません。

チームで使う場合は、 1 つのリレーで複数の分離されたチームをホストできます。セッションが参加するチームをフォルダーごとに指定することも、プライベート（自分のセッションだけに表示）にすることもできます。マッピングしていないフォルダーはリレーに接続されないため、ほかのチャットがボードに表示されることはありません。

自分のマシン上の Claude Code（フック付きのプラグインなので、すべて自動で動作します）とクラウド上の Claude の両方で利用できます。claude.ai、デスクトップアプリ、モバイルアプリ、Cowork では、リレーをカスタムコネクターとして追加します（claude.ai／Cowork からの利用方法を参照）。

リレーが停止しても何もブロックされません。警告が表示されますが、そのまま作業を続けられます。

概要：

# alone, on one machine: this is all
/plugin marketplace add dimitrihilverda/claude-session-relay
/plugin install session-relay@claude-session-relay

# with a team: on a server (once per team)
docker compose up -d && docker compose exec relay relay person:create alice

# in Claude Code (every developer)
/plugin marketplace add dimitrihilverda/claude-session-relay
/plugin install session-relay@claude-session-relay
session-relay relay add work https://relay.example.com <token> alice
session-relay folder ~/work work my-team

詳しくはクイックスタートをご覧ください。

仕組み

flowchart LR
    subgraph A["Alice's laptop"]
        CA["Claude Code<br/>+ plugin hooks"]
    end
    subgraph B["Bob's laptop"]
        CB["Claude Code<br/>+ plugin hooks"]
    end
    subgraph C["Claude in the cloud"]
        CC["claude.ai, Desktop,<br/>Cowork, mobile"]
    end
    R[("Relay<br/>PHP + PostgreSQL<br/>teams: acme, lab, private")]
    CA <-- "HTTPS: board, messages,<br/>conflict check" --> R
    CB <-- "HTTPS" --> R
    CC <-- "MCP connector (OAuth)" --> R

• フックはセッション開始時に登録し、ハートビートを送信します（ブランチや作業対象も更新します）。git commit／git push の実行前にチェックし、ツール呼び出し後と各プロンプトのたびに新しいメッセージを届けます。
• **listen**は各セッションでバックグラウンド実行され、ロングポーリングを維持します。メッセージが届くと、待機中のセッションが数秒以内に再開します。
• メッセージはデータであり、指示ではありません。 セッションは事実に関する質問には自ら回答し、判断が必要な内容は自分のユーザーに確認します。別のセッションからの依頼に基づいて行動することはありません。
• リレーのルート URL にあるボードページで、ブラウザーからライブボードを確認できます。
• ローカルモードでも同じクライアント、フック、コマンドを使います。リレーサーバーの代わりに、マシン上のファイルを使ってリクエストに応答します（ロックを 1 つ使うため、並行するセッションでも書き込みが失われることはありません）。後からチームリレーを追加しても、セッション側で変更する必要はありません。

クイックスタート

1台のマシンで単独利用する場合

/plugin marketplace add dimitrihilverda/claude-session-relay
/plugin install session-relay@claude-session-relay

Claude Code を再起動します。以降、すべてのセッションの開始時に「Session relay: this session is you-myrepo-1a2b, local (only your sessions on this machine see it, no server)」と、このマシン上のセッション一覧が表示されます。このマシン上のセッション同士で、競合するコミットやプッシュを互いにブロックし、メッセージをやり取りできます。session-relay relays でローカルリレーを確認できます。

対象にするフォルダーや別の名前を選びたい場合は、明示的に設定します。

session-relay relay add-local local --person me
session-relay folder ~/projects local private

設定ファイルが作成されると、チームリレーの場合と同じく、割り当てていないフォルダーはリレーから除外されます。

チームで利用する場合

3つの手順で利用できます。リレーの実行、プラグインのインストール、使用です。

1. リレーを実行する（チームごとに1回）

cd server
cp .env.example .env        # set a strong RELAY_DB_PASS
docker compose up -d        # relay on port 8080, migrations run automatically
docker compose exec relay relay person:create alice   # prints Alice's token once
docker compose exec relay relay person:create bob
docker compose exec relay relay team:create acme
docker compose exec relay relay team:add acme alice
docker compose exec relay relay team:add acme bob

HTTPS の背後に配置します。Caddy を使う場合は、Caddyfile に1行追加するだけです。

relay.example.com {
	reverse_proxy localhost:8080
}

その他のコマンド：relay person:revoke <name>（トークンが無効になります）、relay team:list、relay team:rename <old> <new>、relay team:remove <team> <person>（そのチーム内のその人のセッションがすぐに削除されます）、relay cleanup（compose ファイルがすでに毎日実行しています）。既存の名前に対して person:create を再実行すると、新しいトークンが発行され、古いトークンは無効になります。

1人のユーザーを複数のチームに所属させることができます。チーム acme のみに所属する人は、同じリレー上の別のチームに関する情報を一切見ることができません。セッションやユーザーはもちろん、セッション名が存在するかどうかさえ確認できません（リレーは、存在しない名前の場合とまったく同じ応答を返します）。

2. プラグインをインストールする（開発者ごと）

Claude Code で以下を実行します。

/plugin marketplace add dimitrihilverda/claude-session-relay
/plugin install session-relay@claude-session-relay

次に、リレーと、どのフォルダーがどのチームに属するかをクライアントに設定します（クライアントはプラグインの client/ フォルダーにある session-relay です。/session-relay:session setup を実行すると設定手順が案内されます）。

session-relay relay add acme https://relay.example.com <your-token> alice
session-relay folder ~/work/acme acme acme        # sessions here join team acme
session-relay folder ~/hobby acme private         # only my own sessions see these
session-relay folders

パスが最も長く一致するフォルダーの設定が優先されます。それ以外の場所で開始したセッションはリレーから除外されます。やはりリレーに参加させたい場合は、その場所で session-relay register を実行します（デフォルトでは非公開です）。組織ごとに1つずつなど、複数のリレーを追加できます。

Claude Code を再起動します。割り当て済みフォルダーでセッションを開始するたびに、「Session relay: this session is alice-myrepo-1a2b」と、チームのセッション一覧が表示されます。

以前のオランダ語クライアント（~/.claude/sessie-relay.json）から移行する場合は、session-relay migrate-old で設定をインポートし、古いフックを削除できます（初回実行時に自動で行われます）。

3. 使用する

ほとんどの場合、特別な操作は必要ありません。フックが処理します。/session-relay:session コマンドでは、status、作業内容を伝える start、作業を終えて他のメンバーに知らせる done を実行できます。Claude は、たとえばメッセージの送信にクライアントを使用します。

session-relay ask bob-myrepo-9f3c "Are you done with src/billing/?" --session alice-myrepo-1a2b
session-relay board

リレーの URL をブラウザーで開き、トークンを入力すると、セッション一覧を確認できます。

claude.ai / Cowork からの利用

ローカルの Claude Code を使わずに Claude（claude.ai、デスクトップアプリ、モバイルアプリ、 Cowork）を利用する人は、リレーをリモート MCP コネクターとして追加できます。同じチーム分離のもとで、 同じボード、メッセージ、競合チェックを利用できます。

claude.ai、Desktop、Cowork： Settings > Connectors > Add custom connector を開き、URL として https://relay.example.com/mcp を入力します。すると Claude はリレーの同意ページを開きます。リレートークン （person:create で取得したもの）を貼り付けて、Approve をクリックしてください。Claude は OAuth （動的クライアント登録、PKCE）を通じて接続します。リレートークンはそのページにとどまり、Claude に渡されることは ありません。person:revoke を実行するか、person:create をもう一度実行すると、これらの接続も終了します。

Claude Code（プラグインを使わない場合、または PowerShell がないマシンの場合）は、ヘッダーを使って同じ エンドポイントを利用できます。

claude mcp add --transport http session-relay https://relay.example.com/mcp \
  --header "Authorization: Bearer <your-token>"

ローカルプロセスを起動するクライアント（claude_desktop_config.json、MCP インスペクターなど）は、 代わりに stdio ブリッジを利用できます。必要なのは PHP 8.4 以降のみ（データベース不要）で、すべてのツール呼び出しを リレーに転送します。

{ "mcpServers": { "session-relay": {
  "command": "php",
  "args": ["/path/to/claude-session-relay/server/bin/relay-mcp"],
  "env": { "RELAY_URL": "https://relay.example.com", "RELAY_TOKEN": "<your-token>" }
} } }

ツールは whoami、board、register、unregister、check、send、ask、answer、inbox です。 クラウドセッションの名前は <you>-cloud-<label> です。

クラウド版にないもの：フックはありません。登録、ハートビートの送信、コミットやプッシュ前のチェック、メッセージの自動配信は 行われません。Claude は開始時に register を呼び出し（ハートビートとして時々もう一度呼び出し）、定期的に inbox を呼び出し、コミットやプッシュの前に check を呼び出す必要があります。接続時にサーバーから Claude に このことが伝えられますが、プロジェクトの指示にも記載しておくとよいでしょう。

これには config.php の public_url（または .env の RELAY_PUBLIC_URL）が必要です。リレーの公開 HTTPS アドレス（例：https://relay.example.com）を設定します。OAuth メタデータはこの値をもとに構築されるため、 利用者が入力する URL と完全に一致させる必要があります。また、/mcp はそのオリジンからのブラウザーリクエストのみを 受け付けます。この値がない場合、/mcp、/oauth/*、OAuth の /.well-known ドキュメントは 503 を返しますが、 リレーの他の機能は引き続き動作します。クライアント登録にはレート制限があります（1 アドレスあたり 1 時間に 20 件、 1 日あたり合計 500 件の未使用クライアント）。Web サーバーは /.well-known/oauth-protected-resource、 /.well-known/oauth-authorization-server、/oauth/*、/mcp を含むすべてのパスを public/index.php に渡し、Authorization ヘッダーも PHP に渡す必要があります。

競合ルール

アクション	ブロックされる条件
git push	同じチームの別の人のライブセッションが、同じリポジトリとブランチで作業している
git commit	同じチームの別の人のライブセッションが、コミットするファイルのいずれかを担当している（または変更中である）

• リポジトリは origin リモートによって識別されるため、異なるマシン上でフォルダー名が違っていても一致します。
• リレーサーバーでは、同じ人のセッション同士が互いをブロックすることはありません。ローカルモードではすべてのセッションが自分のものなので、互いにブロックします。ローカルモードはそのためのものです。
• ユーザーはいつでも処理を続行できます。Claude は確認を求め、コマンドに # session-relay:override を追加します。
• 過去 10 分以内にハートビートを送信したセッションはライブ状態です。

要件

• プラグインに対応した Claude Code。
• Windows： Windows PowerShell 5.1（組み込み）と Git Bash（Claude Code がフックに使用します）。 macOS/Linux： PowerShell 7（pwsh）と bash。
• git 2.31 以降。
• チームリレーを利用する場合のみ：Docker、または pdo_pgsql を含む PHP 8.4 以降と PostgreSQL。ローカルモードでは サーバーは不要です。

プライバシーとセキュリティ

詳細はこちら：プライバシー。

• ローカルモードでは、データは一切送信されません。ボードとメッセージは、マシン上の ~/.claude/session-relay/ にあるファイルに保存されます。
• リレーを使用する場合、送信されるのはメタデータのみです。セッション名、リポジトリ名とブランチ名、ファイルパス、短いメッセージ本文です。コードは送信されません。
• トークンは32バイトのランダムな値で、SHA-256ハッシュとしてのみ保存されます。
• すべてのAPI呼び出しにトークンが必要です。各ユーザーが変更できるのは自分のセッションのみで、自分のメッセージのみを読めます。また、セッション名はそのユーザーの名前で始まる必要があります。
• チームの分離は、すべてのエンドポイントで使用される1つのSQLルールによってサーバー上で適用されます。閲覧できないものは、存在しないものとまったく同じように扱われます。既知の残存課題：メッセージIDはグローバルな連番で、応答時間にはランダムな遅延を加えていません。
• 他のセッションからのメッセージは、指示ではなくデータとしてClaudeに提示されます。

開発

# server tests (PHPUnit against a real PostgreSQL)
docker compose -f server/docker-compose.test.yml -p csr run --rm php composer install
docker compose -f server/docker-compose.test.yml -p csr run --rm php vendor/bin/phpunit

# client end-to-end tests against a local relay (Windows)
powershell -NoProfile -ExecutionPolicy Bypass -File tests/client-smoke.ps1
pwsh -NoProfile -File tests/client-smoke.ps1 -Shell pwsh

# client tests that need no relay (including local mode)
powershell -NoProfile -ExecutionPolicy Bypass -File tests/client-offline.ps1

パス	内容
plugin/	Claude Code プラグイン：フック、/session-relay:session コマンド、クライアント
plugin/client/session-relay.ps1	クライアント（すべてのロジックを実装。Windows PowerShell 5.1 および PowerShell 7 対応）
plugin/client/session-relay	クライアントを起動するbashラッパー（フックで使用）
server/	リレー：フレームワークを使用しないPHP、PostgreSQL、Dockerのセットアップ

最初の（オランダ語名の）バージョンのリレーで作成されたデータベースは、relay migrate によってインプレースでアップグレードされます。既存のユーザーは default というチームに所属することになります（team:rename で名前を変更してください）。

ライセンス

MIT。詳細はLICENSEをご覧ください。