--- title: "starbridge-mod" url: "https://claudemods.dev/ja/builds/starbridge-mod-b2ab70" source: "https://github.com/T0mSIlver/starbridge/tree/main/mod" source_type: "github" repo: "https://github.com/T0mSIlver/starbridge/tree/main/mod" author: "T0mSIlver" author_handle: "T0mSIlver" stars: 2 category: "ワークフロー・CI" categories: ["workflow"] tags: ["claude-code", "hooks", "human-in-the-loop", "mod", "starbridge", "workflow"] permission_level: 3 scan_complete: true install: "claude plugin marketplace add T0mSIlver/starbridge\nclaude plugin install starbridge-mod" added: "2026-10-09T05:19:32.754Z" updated: "2026-10-10T05:46:06Z" locale: "ja" content_locale: "ja" --- # starbridge-mod オーナーの Starbridge の回答を、要求した Claude Code セッションに送信します。Claude Code モッド：モッドを読み込めないビルドではこれをスキップし、starbridge プラグインは動作し続けます。 ## Description # Claude Code 用 Starbridge モッド オーナーが決定に回答すると、このモッドは回答を、要求した Claude Code セッションに、`starbridge wait` が出力する行として送信します： ``` Answer to d_Xk3… (Merge #12 now?): Merge ``` これはターミナル、デスクトップアプリのコードタブ、リモートコントロールで動作します。 ## インストール `starbridge` プラグインの隣にある Starbridge マーケットプレイスから インストールします（`plugin/README.md`）： ```bash claude plugin install starbridge-mod@starbridge --scope user ``` モッドを拒否する Claude Code ビルドまたは組織はこのプラグインをスキップし、 スキルを保持します。その場合、回答はセッションが `starbridge answers` を実行するまで待機します。 単一セッションでチェックアウトを試すには：`claude --plugin-dir mod`。 ## 仕組み このモッドはキーを保持しません。各対話セッションは 2 つのパスのいずれかを選択し、 エージェントの開始または停止時に切り替えます。 ### エージェント経由 マシンのエージェント（`starbridge agent`、PROTOCOL.md、「ローカルエージェント API」）が その unix ソケットで応答するとき、各セッションは `$.http.fetch` でそれと通信します： - セッション ID ごとに 1 回 `POST /v1/sessions//hello` を、セッションの 作業ディレクトリとともに送信します。 - `GET /v1/sessions//events?wait=25` を連続して実行します。これはモッドからの 呼び出しに対する 30 秒の制限内です。エージェントは、セッションが質問した決定への回答のみをそのセッションに渡します。 - モッドは各イベントの行を送信し、次に `POST /v1/sessions//ack` で 確認します。エージェントは未確認のイベントを再度渡します。 知らないイベントタイプはスキップします。 - セッションの終了時に `POST /v1/sessions//bye` を送信します。 ソケットは `$STARBRIDGE_AGENT_SOCKET`、それ以外の場合はデフォルト設定ディレクトリに対して `$XDG_RUNTIME_DIR/starbridge/agent.sock`、 それ以外の場合は設定ディレクトリ内の `agent.sock` です（CLI の計算方法と同じ）。Windows では （`OS=Windows_NT`）、設定ディレクトリ内のポートファイル `agent.port` であり、 これがループバックポートとすべての呼び出しが運ぶトークンを示します（PROTOCOL.md）。426（エージェントが 別の API リビジョンを話す）または接続できない呼び出しは、セッションを CLI パスに送ります。 ### CLI 経由で エージェントがない場合、または `STARBRIDGE_NO_AGENT=1` の場合、mod は CLI を実行し、 30 秒ごとにエージェントを確認します。 - すべての対話セッションは mod を実行しますが、ポーリングするのはマシンごとに 1 つだけです。 それは `~/.config/starbridge/mod-poller.json` のリースを保持するセッションです。これは `starbridge answers --session --wait 25` を連続して実行し、mod からの呼び出しの 30 秒制限を 下回り続けます。 - 他のセッションは `state.json` を監視します。それが変わると、`starbridge answers --session ` を実行します。これはローカル状態のみを読み取ります。 - `answers` は、そのセッションが尋ねた決定に対する回答のうち、どの `wait` も出力していないものだけを返します。mod は各行を送信し、次に `starbridge answers --session --ack ` でそれを確認します。CLI は 未確認の行を再び引き渡します。 - ポーリングしないセッションも、`state.json` が変わっていないときは 30 秒ごとに `answers` を実行します。変更が見落とされた場合に備えるためです。 - セッションが終了すると、リースを放棄し、別のセッションが ポーリングを開始します。 どちらの経路でも、`/clear` または `/resume` の後、mod は新しいセッション id を使います。`/clear` の間に到着した行は、未確認のまま古い セッションを待ちます。エラーの後、mod は 2 秒待ち、その後さらにエラーが起きるたびに待ち時間を倍にし、 最大 1 分まで待ち、呼び出しが成功するまで ステータス行にエラーを表示します。 ## Pi `pi/starbridge.ts` は Pi 拡張機能としての同じ回答ループです。これは リポジトリの Pi パッケージに `starbridge` スキルとともに同梱されます。`starbridge setup` はそれを、 実行する CLI のリリースタグ、つまり `v` と `starbridge --version` が出力するものにインストールします。 ```bash pi install git:github.com/T0mSIlver/starbridge@v ``` 対話または RPC の Pi セッションでは、各回答をユーザーメッセージとして送信します。 これは Pi がアイドルならターンを開始し、ビジーなら現在のターンの後に実行されます。また、プラグインのルール（`plugin/hooks/rule.md`）を Pi のシステム プロンプトに追加します。`pi -p` はループを取得しないため、そこの `starbridge ask` はエージェントに `starbridge wait` するよう伝えます。 [pi-permission-system](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) がインストールされていると、`pi/permissions.ts` はそのオーソライザーチェーンに `starbridge` リンクを登録し、 オーナーはそれを `config.json` の `"authorizerChain": ["starbridge"]` で 有効にします（`starbridge config permissions on` はそれを追加することを提案します）。ルールが `ask` と言うと、リンクは Claude Code のフックと同様に `starbridge hook permission --agent pi` を実行し、デバイスの許可（今回の 呼び出しのみ: チェーンはリンクがセッションに対して許可することは決してありません）または拒否と そのメッセージを返します。その間、Pi は「ここで回答」を表示し、これがデバイスからプロンプトを取り戻し、 pi-permission-system 自身のダイアログを開きます。リンクは、`starbridge config permissions` がオフのとき、 マシンがペアリングされていないとき、またはサーバーが応答しないとき、そして 570 秒後に、 直ちにそのダイアログに委ねます。 ## opencode `opencode/starbridge.ts` は、opencode プラグインとしての同じ応答ループです。 `starbridge setup` はそれを、`hooks/` からインポートするファイルと ルールとともに `~/.config/opencode/starbridge/` へコピーし、 `~/.config/opencode/plugins/starbridge.ts` をそこへ向けます。 opencode はコマンドにセッション id を与えないため、プラグインの `shell.env` フックが それらに `STARBRIDGE_OPENCODE_SESSION` とそのセッションのタイトルを設定し、その セッションのループを開始します。各回答は `promptAsync` で投入されます。アイドルの セッションはターンを開始し、ビジーのセッションは次のステップで受け取ります。 `opencode run` はループを得ないため、`starbridge ask` はそこのエージェントに `starbridge wait` を実行するよう伝えます。ルールは `experimental.chat.system.transform` を通じてシステムプロンプトに入ります。 各 `permission.asked` イベントは `starbridge hook permission --agent opencode` を実行し、`starbridge config permissions` がオフの間は即座に終了します。 その間 opencode のダイアログは表示されたままです。デバイスの回答は opencode の返信ルートを通じて送られ、キーボードでの回答は CLI を停止させ、 デバイス上でプロンプトを確定します。 デバイスには Allow が承認する内容が見えます。`bash` ではコマンド、`edit` では パスと diff で、これはその edit、write、apply_patch ツールが尋ねるもので、 移動がファイルをどこへ運ぶか、パッチがどのファイルを削除するかを含みます。 そのシェルからの `external_directory` の問い合わせではディレクトリとコマンドです。 他の権限はそのパターンとメタデータを表示します。MCP ツール呼び出しはツール名 のみを表示します。opencode の権限イベントはその引数を一切運ばないためです。 8,000 文字を超えると、CLI は最長の文字列を切り詰め、その旨を伝えます。 各 `question.asked` イベント（opencode の `question` ツールの呼び出し）は `starbridge hook question --agent opencode` を実行し、これは各質問をその ラベルを選択肢として投稿し、すべてが揃ったら回答を出力します。プラグインは それらを `POST /question/{id}/reply` で送ります。キーボードでの回答または Esc （`question.replied` または `question.rejected`）は CLI を停止させ、デバイス上で 質問を確定します。 ## 開発 ```bash pnpm --filter @starbridge/mod test ``` `e2e/run.ts` は、tmux 内の実際の Claude Code セッションを通じて各ケースを駆動します：アイドル、ターン中、`/clear` と `/resume`、ホットリロード、サーバー障害、および同時に 2 つのセッション。これは、ランダムポート（`--local`）上のサーバーアプリに対して、またはテストデバイス（`e2e/device.ts`）とこのマシンの CLI 設定を備えた実際のサーバーに対して実行されます。`claude`、`tmux`、`starbridge` が `PATH` 上にある必要があり、ケースごとに 1 行のタイミングを出力します。`--agent` を指定すると、実行全体を通じて `starbridge agent` を実行し、最後の行で、すべてのセッションがそれを介して応答したことを確認します。 テストは、CLI、実際のエージェント、および実際のサーバーに対して両方のパスを実行し、`@starbridge/server/test-support` がランダムポートで起動します。`hooks/agent.ts` はエージェントパス、`hooks/poller.ts` は CLI パス、`hooks/switch.ts` はどちらかを選択し、`hooks/register.ts` はそれらをエンジンに接続します。CI は `register.ts` 以外のすべてを型チェックします。`register.ts` を型チェックするには、エンジンがその型を `.claude-plugin/types/` に書き込むように mod を一度ロードし、`tsc -p tsconfig.engine.json` を実行します。 ## Install ``` claude plugin marketplace add T0mSIlver/starbridge claude plugin install starbridge-mod ``` ## Original README # Starbridge mod for Claude Code When the owner answers a decision, this mod submits the answer into the Claude Code session that asked, as the line `starbridge wait` prints: ``` Answer to d_Xk3… (Merge #12 now?): Merge ``` It works in the terminal, the desktop app's Code tab and Remote Control. ## Install Install it from the Starbridge marketplace, beside the `starbridge` plugin (`plugin/README.md`): ```bash claude plugin install starbridge-mod@starbridge --scope user ``` A Claude Code build or organization that refuses mods skips this plugin and keeps the skill; answers then wait until a session runs `starbridge answers`. To try a checkout in one session: `claude --plugin-dir mod`. ## How it works The mod holds no keys. Each interactive session picks one of two paths, and switches when the agent starts or stops. ### Through the agent When the machine's agent (`starbridge agent`, PROTOCOL.md, "Local agent API") answers on its unix socket, each session talks to it with `$.http.fetch`: - `POST /v1/sessions//hello` once per session id, with the session's working directory. - `GET /v1/sessions//events?wait=25` back to back, under the 30 s limit on calls from a mod. The agent hands the session only the answers to the decisions it asked. - The mod submits each event's line, then confirms it with `POST /v1/sessions//ack`; the agent hands an unconfirmed event over again. It skips event types it does not know. - `POST /v1/sessions//bye` when the session ends. The socket is `$STARBRIDGE_AGENT_SOCKET`, else `$XDG_RUNTIME_DIR/starbridge/agent.sock` for the default config directory, else `agent.sock` in the config directory, as the CLI works it out; on Windows (`OS=Windows_NT`), the port file `agent.port` in the config directory, which names the loopback port and the token every call carries (PROTOCOL.md). A 426 (the agent speaks another API revision) or a call that cannot connect sends the session to the CLI path. ### Through the CLI With no agent, or with `STARBRIDGE_NO_AGENT=1`, the mod runs the CLI and checks for the agent every 30 s. - Every interactive session runs the mod, but only one per machine polls: the session holding the lease in `~/.config/starbridge/mod-poller.json`. It runs `starbridge answers --session --wait 25` back to back, which stays under the 30 s limit on calls from a mod. - The other sessions watch `state.json`. When it changes, they run `starbridge answers --session `, which reads local state only. - `answers` returns only answers to decisions that session asked and that no `wait` has printed. The mod submits each line, then confirms it with `starbridge answers --session --ack `; the CLI hands an unconfirmed line over again. - A session that does not poll also runs `answers` every 30 s when `state.json` has not changed, in case a change went unseen. - When a session ends, it gives up the lease and another session starts polling. On both paths, after a `/clear` or a `/resume` the mod uses the new session id; a line that arrives during a `/clear` waits, unconfirmed, for the old session. After an error the mod waits 2 s, then twice as long after each further error, up to a minute, and shows the error in the status line until a call succeeds. ## Pi `pi/starbridge.ts` is the same answer loop as a Pi extension. It ships in the repository's Pi package with the `starbridge` skill. `starbridge setup` installs it at the release tag of the CLI it runs, `v` and what `starbridge --version` prints: ```bash pi install git:github.com/T0mSIlver/starbridge@v ``` In an interactive or RPC Pi session it submits each answer as a user message, which starts a turn when Pi is idle and runs after the current one when it is busy. It also adds the plugin's rule (`plugin/hooks/rule.md`) to Pi's system prompt. `pi -p` gets no loop, so `starbridge ask` tells the agent there to `starbridge wait`. With [pi-permission-system](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) installed, `pi/permissions.ts` registers a `starbridge` link in its authorizer chain, which the owner turns on with `"authorizerChain": ["starbridge"]` in its `config.json` (`starbridge config permissions on` offers to add it). When a rule says `ask`, the link runs `starbridge hook permission --agent pi`, as Claude Code's hook does, and returns the devices' allow (this call only: the chain never lets a link allow for the session) or deny with their message. Meanwhile Pi shows "Answer here", which takes the prompt back from the devices and opens pi-permission-system's own dialog. The link defers to that dialog at once while `starbridge config permissions` is off, the machine is not paired or the server does not answer, and after 570 s. ## opencode `opencode/starbridge.ts` is the same answer loop as an opencode plugin. `starbridge setup` copies it, with the files it imports from `hooks/` and the rule, into `~/.config/opencode/starbridge/`, and points `~/.config/opencode/plugins/starbridge.ts` at it. opencode gives commands no session id, so the plugin's `shell.env` hook sets `STARBRIDGE_OPENCODE_SESSION` and the session's title for them, and starts that session's loop. Each answer goes in with `promptAsync`: an idle session starts a turn, a busy one takes it at its next step. `opencode run` gets no loop, so `starbridge ask` tells the agent there to `starbridge wait`. The rule goes into the system prompt through `experimental.chat.system.transform`. Each `permission.asked` event runs `starbridge hook permission --agent opencode`, which exits at once while `starbridge config permissions` is off. opencode's dialog stays up meanwhile: the devices' answer is sent through opencode's reply route, and an answer at the keyboard stops the CLI, which settles the prompt on the devices. The devices see what an Allow approves: the command for `bash`; the paths and the diff for `edit`, which its edit, write and apply_patch tools ask, with where a move takes a file and which files a patch deletes; the directories and the command for an `external_directory` ask from its shell. Other permissions show their patterns and metadata. An MCP tool call shows only the tool's name, since opencode's permission event carries none of its arguments. Past 8,000 characters the CLI cuts the longest string and says so. Each `question.asked` event (a call of opencode's `question` tool) runs `starbridge hook question --agent opencode`, which posts each question with its labels as options and prints the answers once all are in. The plugin sends them through `POST /question/{id}/reply`. An answer or Esc at the keyboard (`question.replied` or `question.rejected`) stops the CLI, which settles the questions on the devices. ## Develop ```bash pnpm --filter @starbridge/mod test ``` `e2e/run.ts` drives real Claude Code sessions in tmux through each case: idle, mid-turn, `/clear` and `/resume`, a hot reload, a server outage, and two sessions at once. It runs against the server app on a random port (`--local`), or against a real server with a test device (`e2e/device.ts`) and this machine's CLI config. It needs `claude`, `tmux` and `starbridge` on `PATH`, and prints one row of timings per case. With `--agent` it runs `starbridge agent` for the whole run, and a last row checks that every session answered through it. The tests run both paths against the CLI, a real agent and the real server, which `@starbridge/server/test-support` starts on a random port. `hooks/agent.ts` is the agent path, `hooks/poller.ts` the CLI path, `hooks/switch.ts` picks one, and `hooks/register.ts` connects them to the engine. CI type-checks all but `register.ts`. To type-check `register.ts`, load the mod once so the engine writes its types to `.claude-plugin/types/`, then run `tsc -p tsconfig.engine.json`.