Claude Bridge

Claude Bridge

独立したコーディングエージェント向けの、ローカルファーストでマシン間のメッセージバスです。

Claude Bridge を使うと、異なるマシン上のコーディングエージェントのセッション間で、名前付きチャネルを介して順序付けられたメッセージを交換できます。リレーはセルフホスト可能で、デフォルトでは SQLite を使用し、MCP、小規模な JSON API、ダッシュボード、ターミナル UI を提供します。

モデル API は呼び出さず、エージェントがファイルシステムやプロセスを共有する必要もありません。Claude Code がこのプロジェクトのきっかけですが、コアは MCP ベースであり、Anthropic には依存していません。

先行開発版に関する注意： このソースツリーは 1.2.0.dev1 として識別されます。最新の安定版 PyPI リリースより先の開発ビルドです。安定版のデプロイを置き換える前に、 変更履歴 と0.9 から 1.2 への移行ガイド を確認してください。

導入する理由

• Windows、macOS、Linux、またはリモートホスト上で、エージェントをそれぞれ独立したセッションで実行できます。
• リモートシェルアクセスを使わずに、作業、結果、レビュー依頼、成果物への参照を送信できます。
• 永続的な履歴とコンシューマーカーソルを使い、クライアントの再起動後に復旧できます。
• 冪等性キーを使って、安全に送信を再試行できます。
• MCP、ブラウザーのダッシュボード、TUI、REST のいずれからも、同じリレーを確認できます。
• 明示的なセキュリティポリシーのもとで、ローカルまたはプライベート LAN／テイルネット上で実行できます。

Claude Bridge はトランスポートであり、自律的なオーケストレーターではありません。メッセージを受信しても、エージェントに実行権限が与えられるわけではありません。

トランスポート

インターフェース	パスまたはコマンド	用途
MCP Streamable HTTP	/mcp	推奨されるリモート MCP トランスポート
MCP stdio	claude-bridge --stdio	ローカルのサブプロセストランスポート
レガシー MCP HTTP+SSE	/sse と /messages/	移行中の既存設定
チャネルイベント SSE	/events/channel/<channel>	ダッシュボード、TUI、カスタムリスナー用。MCP ではありません
JSON API	/api/*	ブラウザー、スクリプト、インテグレーション用

自動テストスイートでは、/mcp に対して実際の MCP SDK ハンドシェイクを実行します。CI ではベンダーのクライアントは起動しません。根拠に基づく互換性マトリックスをご覧ください。

アーキテクチャ

flowchart TB
    A["Claude Code / Codex / MCP client"] -->|"Streamable HTTP /mcp"| B["Claude Bridge"]
    C["Local MCP client"] -->|"stdio"| B
    D["Dashboard / TUI / script"] -->|"REST + event SSE"| B
    B --> E[("SQLite")]

メッセージとライブ通知レコードは、単一のトランザクションで SQLite にコミットされます。HTTP プロセスは、デフォルトでは 500 ms ごとにこの永続的なアウトボックスをポーリングするため、別の stdio プロセスからの書き込みも、接続中のダッシュボード／TUI イベントストリームに反映されます。永続的なチャネル履歴は、再起動後も引き続き信頼できる情報源です。

インストール

python -m pip install claude-code-bridge

ターミナル UI もインストールします。

python -m pip install "claude-code-bridge[tui]"

PyPI の配布パッケージ名は claude-code-bridge です。claude-bridge はすでに無関係な別のプロジェクトに割り当てられていたためです。コマンド名と Python パッケージ名は引き続き claude-bridge と claude_bridge です。

ソースをチェックアウトした場合：

git clone https://github.com/constripacity/Claude-Bridge.git
cd Claude-Bridge
python -m pip install -e ".[dev]"

安全に起動する

HTTP モードは、デフォルトではローカルのみで利用できます。

claude-bridge

これは 127.0.0.1:8765 でリッスンします。ダッシュボードを開くには http://127.0.0.1:8765/ にアクセスするか、http://127.0.0.1:8765/mcp に MCP クライアントを接続してください。

ローカルの stdio モードでは、ネットワークリスナーは起動しません。

claude-bridge --stdio

マシン間サーバー

ネットワークへのバインドは、意図的にフェイルクローズ設計になっています。クライアントが URL に指定するアドレスを信頼済みホストとして指定し、トークンを必須にしてください：

export CLAUDE_BRIDGE_AUTH_TOKEN="$(openssl rand -hex 32)"
claude-bridge \
  --host 0.0.0.0 \
  --trusted-host 100.64.0.10

ここで、100.64.0.10 はサーバーの tailnet アドレスである可能性があります。DNS を使用する構成では、bridge.example.internal のような値を指定します。--trusted-host の値には、URL スキームやパスを含まないホスト名または IP アドレスを指定します。このオプションは複数回指定できます。

次の 2 つの独立したチェックが必要です：

1. --trusted-host は、受け入れる HTTP Host 名を制御します。および
2. Bearer トークンは、保護されたエンドポイントを利用できるユーザーを制御します。

意図的に認証を行わないプライベートテストネットワークでは、トークンを --allow-unauthenticated-network に置き換えてください。これは明示的にリスクを受け入れる設定であり、推奨される本番環境の構成ではありません。

信頼できないネットワーク経由で機密情報を送信する前に、--tls-cert と --tls-key、HTTPS リバースプロキシ、または暗号化されたオーバーレイネットワークを使用してください。信頼モデルの全容については、セキュリティポリシーを参照してください。

コンテナー

公式イメージもフェイルクローズ設計になっています。ネットワークを介したデプロイでは、信頼済みホストと認証ポリシーを指定する必要があります：

export CLAUDE_BRIDGE_AUTH_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 8765:8765 \
  -v claude-bridge-data:/data \
  -e CLAUDE_BRIDGE_AUTH_TOKEN \
  -e CLAUDE_BRIDGE_TRUSTED_HOSTS="100.64.0.10" \
  ghcr.io/constripacity/claude-bridge:latest

SQLite データベースは /data に保存されます。リリースイメージには、完全一致のタグとメジャー／マイナーのタグが使用されます。edge は main を追跡します。

クライアントを接続する

Claude Code

リモート Streamable HTTP：

claude mcp add --transport http -s user claude-bridge \
  http://127.0.0.1:8765/mcp

ローカル stdio：

claude mcp add -s user claude-bridge -- claude-bridge --stdio

保護されたリモートエンドポイントでは、インストール済みの Claude Code のバージョンがサポートするオプションを使用して、対応する Authorization ヘッダーを付加してください。移行中は、従来の構成で引き続き /sse を --transport sse とともに指定できます。

Codex

~/.codex/config.toml でのローカル stdio：

[mcp_servers.claude_bridge]
command = "claude-bridge"
args = ["--stdio"]

リモート Streamable HTTP：

[mcp_servers.claude_bridge]
url = "http://127.0.0.1:8765/mcp"
bearer_token_env_var = "CLAUDE_BRIDGE_AUTH_TOKEN"

これらの例では、各クライアントのドキュメントに記載されたトランスポートを使用しています。このリポジトリの CI で検証するのは MCP プロトコルの動作であり、各ベンダーのクライアントの起動全体ではありません。サポートを表明する前に、互換性マトリクスを参照してください。

MCP ツール

ツール	用途
bridge_send	従来のテキストまたはプロトコル v1 メッセージを送信します。冪等な再試行をサポートします
bridge_receive	メッセージカーソルまたは永続コンシューマーカーソルを使って、上限付きのページを読み取ります
bridge_wait	頻繁なポーリングを行わずに、新しいメッセージを最大 55 秒間待ちます
bridge_ack	コンシューマーのチャネル単位のカーソルを単調に進めます
bridge_channels	アクティブなチャネルと件数を一覧表示します
bridge_ping	ブリッジの健全性と機能を確認します
bridge_status	チャネル全体の最近のアクティビティを要約します
bridge_clear	1 つのチャネルにあるすべてのメッセージ（およびタスク）を削除します
bridge_enqueue	チャネルの作業キューにタスクを追加します（排他的で、一度だけ取得されます）
bridge_claim	リースを使って次のタスクをアトミックに取得します。wait_seconds でロングポーリングします
bridge_complete	lease_token でフェンシングして、取得済みのタスクを完了としてマークします
bridge_fail	取得済みのタスクを失敗として処理します。バックオフを伴って再キューに登録するか、デッドレターにします
bridge_tasks	チャネルのキューを確認します。ステータス別の件数とタスク一覧が表示されます

ツールの結果には、MCP の構造化コンテンツをサポートするクライアント向けの構造化データと、互換性のための読みやすいテキスト表現が含まれます。

信頼性の高いタスク／結果の例

オーケストレーターは、安定した再試行キーを使って構造化タスクを送信します：

bridge_send(
  channel="payments:worker",
  sender="windows-orchestrator",
  idempotency_key="job-802-task",
  message={
    "schema_version": 1,
    "type": "task",
    "content": {"action": "run_tests", "target": "payments"},
    "thread_id": "payments-42",
    "correlation_id": "job-802"
  }
)

ワーカーは、永続化されたコンシューマー ID を使って待機します：

bridge_wait(
  channel="payments:worker",
  consumer_id="mac-worker",
  timeout_seconds=20
)

タスクの適用に成功した後、カーソルを進めます：

bridge_ack(
  channel="payments:worker",
  consumer_id="mac-worker",
  message_id="<processed-message-id>"
)

続いて、同じ thread_id と correlation_id を使って、返信チャネルに結果を送信できます。確認応答によって少なくとも 1 回の処理が保証されますが、任意の外部副作用が厳密に 1 回だけ実行されるわけではありません。

エンベロープ、再試行、カーソル、保持に関する契約の全容は、プロトコルリファレンスに記載されています。

タスクキュー（作業分配）

メッセージはファンアウトされ、すべてのコンシューマーのカーソルにすべてのメッセージが表示されます。これとは逆に、タスクキューでは各タスクが必ず 1 つのワーカーだけに割り当てられます。ワーカーエージェントのフリートをチャネルに接続すれば、タスクが二重に処理されることなく作業を分担できます。

オーケストレーターは、冪等性キーを使って重複を安全に処理しながらタスクをキューに追加します。

bridge_enqueue(
  channel="builds",
  payload={"repo": "payments", "action": "run_tests"},
  max_attempts=3,
  idempotency_key="build-802"
)

各ワーカーは次のタスクを取得し、リース（可視性タイムアウト）を保持します。2 つのワーカーに同じタスクが割り当てられることはありません。wait_seconds を指定すると、空のキューをロングポーリングします。

bridge_claim(channel="builds", consumer="worker-3", lease_seconds=300, wait_seconds=20)
# -> { task_id, payload, attempts, lease_token, lease_expires_at }

リースの期限が切れる前にタスクを完了します。成功時は complete、再試行時は fail を使います。どちらも lease_token によってフェンシングされるため、再取得されたタスクが誤って上書きされることはありません。

bridge_complete(channel="builds", task_id="tsk_…", lease_token="…", result={"passed": 105})
bridge_fail(channel="builds", task_id="tsk_…", lease_token="…", requeue=true, retry_delay_seconds=30)

ワーカーがクラッシュしてタスクを解決できなかった場合、リースの期限が切れるとタスクは自動的に再キューイングされます。max_attempts の上限に達すると、デッドレターキューに送られます。これは少なくとも 1 回の配信となるため、タスクハンドラーは冪等にしてください。bridge_tasks(channel="builds") を使うと、キューのステータス別件数を確認できます。

チャネル

チャネルは初回の書き込み時に作成されます。わかりやすい命名規則は <project>:<purpose> です。

payments:orchestrator
payments:worker
payments:events
payments:review
general:status

チャネル名はルーティングに使われるものであり、認可には使われません。現在の共有トークンモデルでは、認可されたクライアントであれば、どのチャネルでも読み取り、書き込み、クリアが可能です。

ダッシュボード、TUI、JSON API

--no-dashboard を使用しない限り、ダッシュボードは / で提供されます。ダッシュボードは JSON API とチャネルごとのイベントストリームを利用します。React アプリケーション、フォント、その他のランタイムアセットはパッケージにバンドルされているため、ダッシュボードの読み込み時にサードパーティの CDN に接続することはありません。静的アプリケーションには、制限的なコンテンツセキュリティポリシーが適用されます。

TUI を起動します。

python -m claude_bridge.tui
python -m claude_bridge.tui \
  --url http://100.64.0.10:8765 \
  --sender mac

TUI は環境変数から CLAUDE_BRIDGE_AUTH_TOKEN を読み込むため、秘密情報がプロセスのコマンドラインに表示されません。

主要な HTTP エンドポイント：

エンドポイント	目的
GET /status	認証不要の最小限のヘルスチェック
GET /api/state	チャネル数、送信者、バージョン、稼働時間
GET /api/messages?channel=X&since_id=Y&limit=N	件数を制限したチャネル履歴
GET /api/messages/{id}	1 件のメッセージ詳細
GET /api/wait?channel=X&consumer_id=Y	コンシューマーまたはメッセージカーソルを使った、件数を制限したロングポーリング
POST /api/send	冪等性を任意で指定して、従来形式のテキストまたは protocol-v1 メッセージを送信
POST /api/ack	永続コンシューマーカーソルを 1 つ進める
POST /api/clear	チャネルを 1 つクリア
GET、POST、DELETE /api/session	不透明なダッシュボードセッションの確認、作成、取り消し
GET /api/audit?limit=N	監査機能が有効な場合の最近の監査イベント
GET /events/channel/<channel>	再生件数を制限したライブイベントストリーム

バッファーがいっぱいになると、イベントストリームは応答の遅いサブスクライバーを切断することがあります。正確な情報は永続履歴を参照してください。最後のメッセージ ID を使って再接続し、cursor_stale または replay_truncated が返された場合は、履歴を明示的に取得してください。

認証とブラウザーの境界

CLAUDE_BRIDGE_AUTH_TOKEN、--auth-token-file、または --auth-token を設定します。CLI に直接指定した場合、その値がプロセス一覧に表示されることがあります。環境変数またはアクセス権を制限したファイルの使用を推奨します。

有効にすると、保護対象の REST、MCP、イベントエンドポイントでは、次の形式が必要です。

Authorization: Bearer <token>

/status は公開されたままで、意図的に最小限の情報のみを返します。静的なダッシュボードのシェルにはアクセスできる場合がありますが、保護対象のデータ API では引き続きトークンが必要です。

安全でないブラウザーからの変更操作は Origin によって制限され、JSON エンドポイントでは JSON のメディアタイプが必須です。また、Host ヘッダーは許可リストによって制限されます。追加のブラウザーオリジンは、繰り返し指定できる --cors-origin フラグで個別に設定します。

ダッシュボードは Bearer トークンを POST /api/session に一度送信し、短期間有効な不透明の HttpOnly、SameSite=Strict Cookie を受け取ります。マスタートークンがローカルストレージや URL に書き込まれることはありません。イベントストリームはこの Cookie で認証され、?token= によるクエリ認証は拒否されます。ログアウトするとセッションは取り消され、サーバーを再起動すると、メモリ内のダッシュボードセッションはすべて無効になります。

設定

CLI／環境変数	デフォルト	用途
--host	127.0.0.1	HTTP バインドインターフェース
--port	8765	HTTP ポート
--db / CLAUDE_BRIDGE_DB	./claude-bridge.db	SQLite のパス
--trusted-host / CLAUDE_BRIDGE_TRUSTED_HOSTS	ループバックホスト	許可する Host 名／IP アドレス
--auth-token-file / CLAUDE_BRIDGE_AUTH_TOKEN	未設定	共有 Bearer 認証
--allow-unauthenticated-network	オフ	ループバック以外での認証を明示的に回避
--cors-origin / CLAUDE_BRIDGE_CORS_ORIGIN	同一オリジンのみ	別の localhost ポートを含む追加のブラウザーオリジン
--tls-cert + --tls-key	未設定	HTTPS リスナーを直接起動
--retention-days / CLAUDE_BRIDGE_RETENTION_DAYS	0	N 日より古いメッセージを削除します。0 の場合は保持します
--audit-log / CLAUDE_BRIDGE_AUDIT_LOG	オフ	セキュリティ関連イベントを記録
CLAUDE_BRIDGE_AUDIT_RETENTION_DAYS	90	監査履歴の保持期間
CLAUDE_BRIDGE_SESSION_TTL_SECONDS	28800	ダッシュボードセッションの不透明な有効期間
CLAUDE_BRIDGE_EVENT_POLL_MS	500	プロセス間のアウトボックスポーリング間隔
CLAUDE_BRIDGE_EVENT_RETENTION_DAYS	7	配信済みアウトボックスレコードの保持期間
--no-dashboard	オフ	ブラウザーアセットをマウントしない
CLAUDE_BRIDGE_MAX_REQUEST_BYTES	262144	HTTP リクエストボディの最大サイズ
CLAUDE_BRIDGE_MAX_MESSAGE_BYTES	131072	エンコードされたメッセージの最大サイズ
CLAUDE_BRIDGE_MAX_SSE	100	チャネルイベントのサブスクライバー総数
CLAUDE_BRIDGE_MAX_SSE_PER_CHANNEL	25	1 つのチャネルのサブスクライバー数
CLAUDE_BRIDGE_SSE_REPLAY_LIMIT	500	再接続時のバックログ上限
CLAUDE_BRIDGE_STATELESS_HTTP	オフ	ステートレスな Streamable HTTP セッションを使用

対応するフラグがある場合は、CLI の値が優先されます。無効な数値または ブール値の環境変数があると、起動時に設定エラーが発生します。

永続化と運用上の制限

• SQLite は WAL モードで動作し、個人または小規模チーム向けのリレーに適しています。
• このサーバーは、現時点ではマルチノードまたは高可用性のメッセージブローカーではありません。
• 1 つの HTTP ワーカーと連携する stdio プロセスは WAL データベースを共有でき、 永続アウトボックスによってライブイベントが伝播されます。これは小規模向けの SQLite 設計であり、マルチノードまたはエンタープライズ向けのブローカーではありません。
• 保持期間の設定により古いカーソルが無効になる場合があります。重要な成果物は ブリッジの履歴だけでなく、リポジトリまたはアーティファクトストアに保存してください。
• 共有 Bearer トークンでは、ユーザーの識別やチャネルごとの権限設定はできません。
• 再現可能なベンチマークと環境がない限り、ベンチマークに関する主張は行いません。

今後の運用および認可に関するマイルストーンについては、 ロードマップをご覧ください。

開発

python -m pip install -e ".[dev]"
ruff check claude_bridge tests
pytest -v
python -m build

CI では Linux 上で Python 3.10～3.13 のテストを実行し、Windows と macOS では 現行バージョンのスモークテストを実行します。実際のソケットを使用する MCP テストでは、 公式 SDK を通じて初期化、ツール一覧表示、送信、受信、待機、確認応答を検証します。 別のジョブでは sdist と wheel をビルドし、メタデータを検証してから、各アーティファクトを クリーンな環境にインストールし、CLI を確認します。

新しい機能を提案する前に、貢献ガイドを お読みください。脆弱性については、公開 issue ではなく、 セキュリティポリシーに記載された非公開の手順をご利用ください。

ロードマップ

現在の順序は次のとおりです。

1. 1.2 — Streamable HTTP のセキュリティ強化、構造化メッセージ、冪等性、永続的なコンシューマー；
2. 1.3 — ネイティブクライアントの診断機能と、実験的な Claude Channels コンパニオン；
3. 1.4 — 個別の ID、スコープ、ACL、クォータ、トークンのローテーション；
4. 1.5 — 可観測性、運用ツール、オプションで利用できるスケーラブルなバックエンド；および
5. 2.0 — 実際の利用状況から必要と判断された場合の、フェデレーションとオプションの A2A アダプター。

各マイルストーンと対象外の項目は、 ロードマップで定義されています。

ライセンス

MIT — ライセンスをご覧ください。

Constripacity によって設立、保守されています。