cli-bridge

cli-bridge — ユーザー自身の starchild バイナリ用の CLI バンドルを発行する

このスキルは、ローカルの clawd 上で新しい AKM キー（scope=chat:bridge:cli）を発行し、 それを sc-chatroom に登録して、短い不透明なコード（sc_xxxxxxxx）と引き換えます。 ユーザーに渡されるバンドルには、その短いコードのみが含まれます — AKM シークレットも Fly マシン ID も決して含まれません。

+----------------+   POST /agent/chat/stream   +-----------------+
| starchild CLI  |   Bearer sc_xxxxxxxx        | sc-chatroom     |
| (user laptop)  | --------------------------> | (gateway)       |
+----------------+                             +--------+--------+
                                                        |
                            resolves sc_… → AKM + container_id
                                                        |
                                                        v
                                          POST /chat/stream (Bearer sk_…
                                          + fly-force-instance-id)
                                          +----------------------+
                                          | user's own clawd     |
                                          | (Fly internal)       |
                                          +----------------------+

生の AKM ではなく短いコードを使う理由

以前のバージョンでは、AKM シークレットと Fly マシン ID を直接バンドルに埋め込んでいました。 それは動作しましたが、2 つの欠点がありました — バンドルをデコードするとルーティング メタデータが漏洩し、バンドルを一度でも保持した相手は永続的な AKM シークレットを 保持することになりました。短いコード形式はその両方を解決します:

• バンドルの base64 デコード結果は {d, c:"", k:"sc_…", s, exp, l} — シークレットも Fly マシン ID も含まれません。
• cli-revoke <sc_…> は短いコードだけを無効化します。基盤となる AKM は生きたままです （それも消したい場合は cli-revoke --akm <prefix> を使用してください）。
• sc-chatroom は AKM シークレットを自社の DB に保持するようになりました。これは意図的な 信頼の移行です — AKM はユーザーのノート PC 上を巡回するのではなく、Fly の内部ネットワーク内に とどまります。

スコープの境界 — まずこれを読んでください

cli-bridge がカバーするのはちょうど 1 つの経路です: ユーザーのローカル CLI が そのユーザー自身の clawd と 1 対 1 で通信する経路です。これはチャットルームの メンバーシップ資格情報ではありません。

ユースケース	正しい資格情報	誤り
個人の CLI ↔ 自分の clawd（このスキル）	chat:bridge:cli AKM（sc_… コードでフロント）	—
sc-chatroom のルームに参加	chatroom join 経由の chat:thread:chatroom-{room_id} AKM	chat:bridge:cli AKM
ゲストとして公開ルームを閲覧	資格情報は不要	いかなる AKM

CLI のインストール

このスキルの以降の部分では、starchild がユーザーの $PATH 上にあることを前提としています — まだない場合は先にインストールしてください。

ワンライナー（OS + アーキテクチャを自動検出）

curl -fsSL https://workroom.iamstarchild.com/install/cli | bash

darwin/linux × arm64/amd64 に適したバイナリを選択し、$PATH 上に配置します （Apple Silicon は /opt/homebrew/bin、Linux は ~/.local/bin にフォールバックします。 sudo はそのディレクトリがユーザー書き込み可能でない場合のみ）、インストール先ディレクトリが まだ $PATH にない場合はユーザーのシェル rc を修正し、自己チェックとして starchild --version を実行します。SHA256 etag により、再実行は安価な「すでに最新」の no-op（HTTP 304、ダウンロードなし）になります。レビュー用のソース: tools/install-cli.sh （__SERVER_URL__ はリクエスト時に書き換えられます）。

Homebrew

brew tap starchild/tap https://github.com/Starchild-ai-agent/homebrew-tap
brew trust starchild/tap
brew install starchild

starchild フォーミュラは macOS (arm64 / amd64) および Linux (arm64 / amd64) 用の バイナリを提供します — brew install がホストに適したものを選択します。このフォーミュラには bottle ブロックがないため、インストール時にサーバー（workroom.iamstarchild.com）から ビルド済みバイナリをダウンロードして $PATH 上に配置する小さな Ruby スクリプトが実行されます — ローカルでのコンパイル手順はありません。後でアップグレードするには: brew update && brew upgrade starchild。

Linux に関する注意: Homebrew 自体は Linux で動作しますが、Ruby + ビルドツールチェーン （一度だけ apt install build-essential ruby / 各ディストリビューションの同等コマンド）を 必要とします。Linux ホストでは、上記のワンライナーはそれをスキップし、機能的に同一であるため、 ユーザーがすでに brew ユーザーでない限り、そちらを優先してください。starchild-app （デスクトップワークスペース）は macOS 専用です — このフォーミュラはソースから ビルドし（rust + node）、意味があるのは macOS ビルドのみです。

確認

starchild --version

ワンライナーを実行した直後で、シェルがまだ command not found と言う場合は、新しいターミナルを 開いてください — PATH の更新は現在のセッションではなく rc に反映されています。

前提条件

chatroom と同じです。

• AKM がこの clawd にインストールされている（POST /api/keys がループバックで動作する）
• AKM が scope="chat:bridge:cli" を受け入れ、/chat/stream ミドルウェアがそのスコープに対して任意の thread_id を許可する（clawd ブランチ aladdin/feat/akm-chatroom で既に提供済み）
• sc-chatroom が POST /cli-keys を含むビルドである（マイグレーション 007 以降）
• FLY_MACHINE_ID（または CONTAINER_ID）環境変数が設定されている
• CHATROOM_PUBLIC_URL 環境変数が sc-chatroom ゲートウェイを指している（デフォルトは https://workroom.iamstarchild.com）
• CHATROOM_SERVER_URL 環境変数が Fly 内部の sc-chatroom を指している（デフォルトは http://sc-chatroom.internal:8080）

コマンド

cli-login — 新しいバンドルを発行する

python3 skills/cli-bridge/scripts/cli_login.py --label "my laptop"
python3 skills/cli-bridge/scripts/cli_login.py --label "codex-vm" --ttl-days 14

デフォルトの TTL は 90 日、最大は 365 日です。出力はユーザーが starchild login にコピーするワンライナーです。バンドルは不透明であり、sc-chatroom が呼び出しごとに解決します。

cli-list — 有効なバンドルを表示する

python3 skills/cli-bridge/scripts/cli_list.py
python3 skills/cli-bridge/scripts/cli_list.py --include-revoked

このユーザーが sc-chatroom で発行したすべての CLI ショートコードを一覧表示します。列：code、issued、expires、uses、label。

cli-revoke — バンドルを無効化する

python3 skills/cli-bridge/scripts/cli_revoke.py sc_xxxxxxxx
python3 skills/cli-bridge/scripts/cli_revoke.py --akm sk_yyyyyy

デフォルト：sc-chatroom のショートコードを無効化します。基盤となる AKM は有効なままです。--akm を付けると：ローカルの clawd 上の AKM も失効させ、それに紐づくすべてのバンドルを無効化します。

agent-shell によるローカルシェル（CLI ≥ v0.2.0）

--enable-shell を付けて発行された cli-login バンドルは、エージェントがユーザー自身のマシンでシェルコマンドを実行することを承認します。たとえば「ノート PC で nginx は動いているか」「~/Downloads を整理して」といった用途です。通常のバンドルはチャットブリッジのみであり、シェルアクセスは付与されません（後述の「シェルはデフォルトで無効」を参照）。ユーザーは小さなデーモンを起動します。

starchild agent-shell            # daemonizes; holds a WS open to your clawd
starchild agent-shell --foreground   # attach to the terminal for debugging
starchild agent-shell-stop       # stop the daemon

agent-shell は、ログイン中のバンドルにシェルが付与されていない場合、起動を拒否します。clawd が拒否するようなチャネルに接続するのではなく、--enable-shell バンドルを取得するようユーザーに伝えます。

デーモンは単一インスタンス（pidfile + flock）で、macOS/Linux のみに対応しています。起動時および定期的に自己更新します。ダウンロードされたバイナリは、交換前に埋め込まれた Ed25519 リリースキーで検証されるため、悪意のある、または MITM された更新サーバーがユーザーのマシンに任意のコードを送り込むことはできません。

仕組み：デーモンはバンドルの sc_… コードを使って wss://<chatroom>/ws/cli-shell に接続します。sc-chatroom はコードを解決し、WebSocket をユーザーの clawd マシンにリバースプロキシします。ノート PC のアップグレードを受け入れ、fly-force-instance-id で固定された自身の上流 WS を clawd に対して開き、両者の間でバイトを転送します（これは fly-replay ではありません。chatroom と clawd は異なる Fly アプリであり、アプリ間のリプレイは 403 で拒否されます）。AKM は上流ホップでサーバー側に注入されるため、ノート PC に到達することはありません。clawd は接続を ShellHubService で保持し、local_shell ツールはシェル対応のノート PC が接続されている間だけ LLM に公開され、ソケット経由でコマンドを送信します。

シェルはデフォルトで無効（ケイパビリティゲート）

cli-login は --enable-shell が渡されない限りシェルを付与しません。AKM が権限の authoritative なソースです。clawd は /ws/cli-shell ハンドシェイク時に AKM を読み取り、shell を持たない接続に対してすべての exec を拒否します（#264）。したがって、漏洩した通常のバンドルはチャット用の認証情報であり、ローカル RCE には決してなりません。

• シェルを付与する：cli_login.py --label … --enable-shell → AKM の capabilities: ["shell"]、バンドルは x: ["shell"] を持つ。
• 既存のシェルなしバンドルをアップグレードする：その場で切り替えることはできません。新しい --enable-shell バンドルを発行し、starchild login でログインし、古いものを cli-revoke してください。権限昇格は常に新規発行を経由します。

エージェントが事前に把握する情報 (ケイパビリティマニフェスト)

接続時に、デーモンは以下を通知する hello フレームを送信します:

• プラットフォーム — os (darwin/linux)、arch (arm64/amd64)、およびアクティブな shell。これによりエージェントは、BSD と GNU のユーザーランドのどちらと 通信しているか、どのパッケージマネージャーを想定すべきかなどを把握できます — ps のフラグを推測したり、ps: illegal option に遭遇したりすることは もうありません。
• ポリシーサマリー — mode (許可ルールが存在しない場合は default-deny、 それ以外は allowlist)、ユーザーの allowed ルール、明示的な denied_extra ルール、および常時有効な builtin_denied リスト。
• ファイル転送ポリシー — transfer_dir (常に許可されるワークスペース)、 yolo フラグ、および ~/.config/starchild/file-policy.toml からの read_allow / write_allow グロブ。バンドルが files ケイパビリティを 持つ場合にのみ存在します。完全なルールについては以下の「ファイルパス ポリシー」を参照してください。この箇条書きは、エージェントがラップトップが ファイル転送を通知したこと自体を把握するためのものにすぎません。

clawd はこれをエージェントのシステムプロンプトに描画します (接続中のみ)。 これによりエージェントは、許可されたコマンドを選択するか、ローカルポリシーが それを禁止していることをユーザーに明示的に伝えることができ、盲目的に 探ることはありません。

セッションの動作

• 接続レベルの cwd。 各コマンドの結果として得られる作業ディレクトリは エコーバックされ (stdout から除去される末尾の pwd センチネル経由)、 次のコマンドのために永続化されるため、セッション内の呼び出しをまたいで cd が実際の意味を持ちます — 完全な PTY のコストや脆さなしに。呼び出し ごとの明示的な cwd はこれを上書きします。
• 出力の切り詰め。 stdout/stderr はそれぞれ 200 行に制限されます (さらにバイト上限もあります)。これにより find / やログダンプが LLM のコンテキストを溢れさせることはありません。切り詰め前の完全な行数が 報告され (stdout_lines / stderr_lines)、truncated: true が設定 されます — エージェントは黙って切り詰めるのではなく、「N 行のうち最初の 200 行を表示中」と伝えることができます。
• ハートビート。 デーモンは 45 秒ごとに ping を送り、アイドル状態の WebSocket を維持します (Fly のエッジは約 2.5 分でアイドルソケットを切断 します)。Exec は goroutine で実行されるため、長時間のコマンドが ハートビートをブロックすることはありません。

ローカル実行ポリシー (唯一の自動実行ガード)

デーモンはヘッドレスで実行される (プロンプトを出す TTY がない) ため、 すべてのコマンドは ~/.config/starchild/exec-policy.toml によって ゲートされます (名前とは裏腹に TOML 依存のない、小さな YAML allow:/deny: 行フォーマットとしてパースされます)。ルールはデフォルトで 部分文字列マッチです。正規表現にするにはルールを / / で囲みます:

allow:
  - "ls"
  - "cat "
  - "/^git (status|log|diff)/"
  - "ps"
deny:
  - "git push"

判定順序: 組み込みの拒否 (常に優先) → ファイルの deny → ファイルの allow → デフォルト拒否。 ファイルに関係なく適用される 2 つの ハードルールがあります:

• 対話的/TTY をブロックするコマンドおよび破壊的なコマンドの組み込み拒否 リストは常に拒否されます: vim/vi/nano/emacs、 less/more/man、top/htop/btop、ssh/telnet、sudo/su/ doas、tmux/screen、reboot/shutdown/halt、および rm -rf、mkfs、dd if=、… | sh、… | bash、> /dev/sd* の形。
• デフォルト拒否: allow ルールにマッチしないものは拒否されます。 したがって、ポリシーファイルがなければポリシーの mode は default-deny となり、ユーザーがコマンドを許可するまで何も実行されません。

制限事項

• 無人ポリシーのみ。 対話的な承認プロンプトはありません。ポリシー ファイルが唯一のガードです。将来のバージョンでは Web 承認ポップアップが 追加されます。
• 同期コマンドのみ。 バックグラウンドジョブ / 進捗ポーリングはまだ ありません。
• macOS/Linux のみ。 デーモンは Windows での実行を拒否します。
• 失効: cli-revoke <sc_…> はショートコードを無効化します。デーモンの 次の再接続は認証に失敗し、チャネルが閉じられます。

agent-shell によるファイル転送 (CLI ≥ v0.3.0)

バンドルが --enable-files 付きで作成された場合、同じ agent-shell デーモンが、ユーザーのマシンとエージェントのワークスペース間の ファイル転送 も提供します。コンテンツはディスクからディスクへストリームされ、 チャットを経由しないため、大容量/バイナリファイル (10MB 以上の PDF、画像、アーカイブ) も動作します。

エージェント向けの 3 つのツール + ユーザー向けの 1 つのコマンド:

• request_upload(laptop_path) — エージェントがノート PC からファイルを取得して workspace/uploads/ に取り込みます (「私の ~/big.pdf を取得して要約して」)。
• write_local_file(src, dst) — エージェントがワークスペースのファイルをノート PC へ送信します (「workspace/output/report.pdf を私の ~/Downloads に保存して」)。src は ワークスペースのパスであり、インラインコンテンツではありません。
• read_local_file(path) — エージェントが確認するために 小さなテキスト ファイルを読み取ります (設定/ログの断片)。大容量/バイナリファイルは request_upload を経由します。
• starchild push <file> — ユーザーが能動的にローカルファイルを エージェントの workspace/uploads/ にアップロードします。これはエージェントのプロンプトで通知されます。

python3 skills/cli-bridge/scripts/cli_login.py --label "laptop" --enable-files
# combine with shell if you want both:
python3 skills/cli-bridge/scripts/cli_login.py --label "laptop" --enable-shell --enable-files

files は shell とは 独立した機能 です — バンドルはどちらか一方、両方、またはどちらも持たないことができます。shell と同様に、デフォルトではオフであり、AKM 上で権威を持ちます (clawd は、それを持たない接続の転送フレームを拒否します)。

ファイルパスポリシー (ノート PC 側、多層)

転送はノート PC 側でパスポリシーによって制御され、厳しい順に適用されます:

1. 組み込みの保護パスは常に拒否されます (--yolo 指定時でも): ~/.ssh、~/.aws、シェル rc (.zshrc/.bashrc/…)、.config/starchild、 launchd/systemd/cron、.git/hooks、ブラウザの Cookie ストア、.env、ssh 鍵。これらに書き込むと永続的な RCE になります。読み取ると認証情報が漏洩します。

2. 専用の転送ディレクトリ (~/starchild-transfer、自動作成) — 読み取り + 書き込みが常に 許可されます。安全なデフォルトのワークスペースであり、これを優先してください。

3. そのディレクトリの外 — パスが ~/.config/starchild/file-policy.toml 内の read_allow / write_allow グロブに一致する か、デーモンが --yolo 付きで起動されている 場合を除き、拒否されます:

   starchild agent-shell --yolo   # allow ANY path (built-in deny still applies)
   

   # ~/.config/starchild/file-policy.toml  (YAML allow-globs)
   read_allow:
     - "~/Documents/*.md"
   write_allow:
     - "~/exports/*.csv"
   

その他の保証: 書き込まれたファイルにはモード 0644 が設定されます (実行可能には決してなりません)。 書き込みはアトミックです (一時ファイル + リネーム、中途半端に書き込まれたターゲットは残りません)。転送ディレクトリから 脱出するシンボリックリンクは拒否されます。転送ごとの上限は 100 MiB で、 チャンク単位でストリームされるため、大容量ファイルが WS フレームの制限を超えることはありません。

セキュリティ上の注意: 実行中の agent-shell (--enable-shell バンドル上) と 許容的なポリシーの組み合わせは、事実上ユーザーのマシン上でのリモートコマンド実行であり、 AKM の TTL、sc_… コードの有効性、およびポリシーファイルによって制限されます。 デフォルトは保守的です: shell は明示的に許可されない限り オフ、ポリシーは コマンドがオプトインされるまで 全拒否、デーモンの自己更新はバイナリを 差し替える前に Ed25519 署名 を検証します。拡張は意図的に行ってください。

agent-shell によるローカル MCP サーバー (CLI ≥ v0.5.32)

agent-shell は、ユーザーのマシンの MCP Host そのもの です。local_shell とファイル転送を 実行する同じデーモンが、~/.config/starchild/mcp-servers.toml も読み取り、有効な各 stdio MCP サーバーを長時間稼働する子プロセスとして起動し、MCP の initialize → tools/list ハンドシェイクを実行し、tools/call を既存の WebSocket 経由で clawd にプロキシします。次に clawd が各リモートツールを mcp__<server>__<tool> として登録し、それらを 現在の 会話に注入します — 新しいセッションは不要です。

これは、クラウドのエージェントからローカルアプリ (Blender、Godot、ローカルの Figma ブリッジ、computer-use、browser-use、ファイルシステムサーバーなど) を操作するための経路です。 エージェントは、ユーザーのマシン上の localhost に他の方法では到達できません。clawd 自身の (直接的な) MCP サポートは、他所でホストされるリモート/HTTP/SSE サーバー向けであり、 ユーザーのノート PC 上で実行する必要があるプロセス向けではありません。

仕組み（制御チャネルは local_shell と同じ WS です）

clawd (cloud agent)
  │  mcp_list / mcp_call frames
  │  (over the existing /ws/cli-shell WebSocket)
  ▼
agent-shell daemon (laptop) ── MCPProxy
  │  stdio JSON-RPC (newline-delimited)
  ▼
blender-mcp / figma-mcp / server-everything / … (one process per server)

ノート PC 側が MCP セッションの状態（initialize → initialized → tools/list、キャッシュ済み）を保持します。clawd は高レベルの mcp_call を送るだけで、生の JSON-RPC を話すことはありません。サーバーからの tools/list_changed 通知を受けると、そのサーバーのツールを再取得して再登録します。

サーバーの設定

~/.config/starchild/mcp-servers.toml を編集します（拡張子は .toml ですが中身は YAML です — exec/file-policy と同じ慣例）。各エントリは次のとおりです。

servers:
  - id: blender
    command: uv
    args:
      - "--directory"
      - "/Users/aladdin/Workspace/StarChild/blender_mcp/mcp"
      - "run"
      - "blender-mcp"
    env:
      - "SOME_KEY=value"
    enabled: true

絶対パスのみ。 $HOME と ~ は展開されません — MCP クライアントはシェルを介さずコマンドを直接起動します。/Users/<name>/... を使用し、~/... や $HOME/... は決して使わないでください。

enabled のデフォルトは true です（enabled: のないエントリは実行されます）。このファイルはホットリロード可能ですが、実行中のセッションが変わるのはデーモンが再起動したときだけです — リロードはパース済みの設定を更新するだけで、セッションの途中でサーバープロセスを起動・終了することはありません。アプリの Settings パネルはこのファイルを書き込み、agent-shell を自動で再起動します。

agent-shell を再起動してもチャットは切断されません

チャットストリーム（ユーザーへの返信）は agent-shell ではなく clawd の HTTP/SSE 経路で流れます。agent-shell の再起動で中断されるのは local_shell / ファイル転送 / mcp_call だけで、それは再接続にかかる約 2 秒間のみです — 会話自体は生き続けます。したがって、設定変更後にデーモンを再起動するようユーザーに伝えること（あるいは local_shell を使って自分で実行すること）が可能です。会話を終わらせてしまうことはありません。

再起動後、デーモンは有効なサーバーとそれぞれの実行時ステータス（ready/failed/not_started）を列挙した mcp_manifest を伴う新しい hello を送信します。clawd は ready な各サーバーを積極的に mcp_list し、ツールを登録します。ターンごとの maybe_resync_local_mcp によるキャッチアップも、hello 時に取得に失敗したサーバー（例: 起動が遅いサーバー）を以降のターンでカバーします。

動的インジェクション — local_mcp_status + local_mcp_reload

設定の編集を反映するために agent-shell を再起動する必要はありません。エージェント向けの 2 つのツールがローカル MCP ランタイムをライブで操作します。

• local_mcp_status — 設定されたすべてのサーバーの実行時状態を返します（ready とツール数、failed とエラー、または not_started）。期待していた mcp__<server>__* ツールが見つからないときにこれを呼び出してください — サーバーの起動に失敗している可能性があります。
• local_mcp_reload — agent-shell に mcp-servers.toml を実行時に再読み込みさせ、新しく追加されたサーバーを起動し、削除されたものを停止するよう要求します。デーモンの再起動もチャットの中断もありません。 リロード後、追加されたサーバーの mcp__<server>__* ツールは次のターンに現れます（ツール一覧はリクエストごとに再構築されます）。設定を編集した後にこれを使えば、ユーザーに何かを再起動してもらうことなく新しいサーバーを利用可能にできます。

ユーザーが今設定したサーバーがツールを表示しない場合の典型的な流れ:

1. local_mcp_status を呼び出す → blender: not_started または failed: … を確認する。
2. （failed の場合は設定を修正する — 不正なパス、依存関係の欠落など）
3. local_mcp_reload を呼び出す → agent-shell が新しいサーバーを起動する。
4. 次のターンで、mcp__blender__* ツールが登録される。

エージェントから見えるもの

• ツールは mcp__<server>__<tool> として表示されます（例: mcp__blender__get_scene、mcp__everything__echo）。これらの description と input_schema はサーバー自身の tools/list から取得されます — ネイティブツールと同様に呼び出せます。
• プロンプトマニフェスト（build_mcp_manifest_section、揮発性の 末尾部分）には、接続されているローカル MCP サーバーと、 そのツール名の一覧が記載されます。サーバーが設定されているのに 起動に失敗した場合も、ここに記載されます（設定は存在するが、未読み込み）。
• 期待していた mcp__<server>__* ツールが表示されない場合、 そのサーバーは起動していません。次の順序で診断してください:
  1. ~/.config/starchild/mcp-servers.toml に enabled: true で 含まれていますか？
  2. 編集の後に agent-shell を再起動しましたか？（設定は起動時に読み込まれます）
  3. デーモンログ（~/.starchild/sc-chatroom[-dev]/cli-shell/agent.log） にはサーバーごとに 1 行あります: 成功時は agent-shell: mcp: <id> ready (N tools)、失敗時は agent-shell: mcp: failed to start <id>: <reason>。local_shell 経由で読んでください。
  4. LOCAL アプリのブリッジを必要とするサーバー（127.0.0.1:9876 上の Blender アドオン、Figma プラグインなど）については、そのブリッジも 実行中であることを確認してください — MCP サーバープロセスは起動できても、 バックエンドアプリに到達できるまでそのツールはエラーになります。

ローカルアプリと通信するために MCP を迂回しないでください

Blender のようなサーバーの登録が遅いと、アプリ自身のブリッジ （127.0.0.1:9876）に生のソケットを開いて Python を直接送りたく なります。やめてください — それは MCP ツールレイヤー（スキーマなし、 ポリシーなし、呼び出しごとの検証なし）を迂回することになり、エージェントは 構造化された mcp__blender__* インターフェースを失います。代わりに MCP サーバーの起動を修正してください（ログを確認し、ブリッジを確認し、 agent-shell を再起動する）。生のブリッジは最後の手段としてのみ使用してください。

サーバーごとの注意事項（バックエンド別）

• Blender MCP（blender-mcp）: 2 つの部分があります — stdio MCP サーバー （uv run）と、Blender アドオンのブリッジ（127.0.0.1:9876 で待ち受け）。 どちらも実行されている必要があります。MCP サーバーは Blender が閉じていても 起動しますが、アドオンのブリッジが起動するまで、すべてのツール呼び出しは エラーになります。Blender.app が開いていても which blender は失敗することが よくあります — それは問題ありません。重要なのはブリッジです。
• Figma: 2 つの異なる Figma MCP があります。figma-mcp-server （REST ラッパー、読み取り専用キャンバス）は bunx 経由でローカルに実行されます。 公式の Figma リモート MCP（書き込み可能キャンバス、SSE）はリモートサーバーです — clawd 側（agent.yaml の mcp_servers:）で設定してください。ここでは ありません。このファイルはノート PC 上で実行されるサーバー専用です。
• computer-use / browser-use: 本質的にローカルです（ユーザーの画面や ブラウザを操作します）。ここで設定してください。

セキュリティ

ローカル MCP サーバーは、ユーザーのマシン上で任意のコードを実行できます （Blender の execute_code、シェルサーバーなど）。mcp-servers.toml に エントリを追加することは、exec ポリシーを広げるのと同じ重大さで扱ってください: ユーザーが求めたサーバーだけを追加し、読み取り専用サーバーを優先し、 シークレット（API キー）をチャットに決して書かないでください — env: フィールドを 使用してください。mcp-servers.toml のパスはデフォルトではファイルポリシーの 許可リストに含まれていません。ユーザーがエージェントに設定を直接書かせたい場合は、 そこに追加してください。

エンドツーエンドのスモークテスト

# 1. Inside agent chat:
@agent give me a cli key for my laptop
# → outputs `starchild login starchild_<base64>` (bundle has sc_… code)

# 2. On laptop:
starchild login starchild_xxx
starchild whoami
starchild "hello, who are you?"
# → starchild sends Bearer sc_… to sc-chatroom; sc-chatroom resolves
# → it to AKM + container_id and forwards to user's clawd

# 3. Revoke the short code from chat:
@agent revoke cli code sc_xxxxxxxx

# 4. Next CLI call should fail at the gateway:
starchild "hello?"
# → "gateway rejected (401) — code may be revoked; ask your agent for a fresh CLI bundle"

パイプ / シェルの組み合わせ（CLI ≥ v0.1.0）

一度ペアリングすれば、starchild はパイプフレンドリーです。位置引数の プロンプトが指定されていない場合は stdin を読み込み、アシスタントの返答を stdout に書き出し、診断情報を stderr に送ります — そのため、あらゆる Unix ツールと組み合わせられます。

# stdin → reply
echo "explain monads in 3 lines" | starchild

# reply → downstream
starchild "what is the OWASP top 10?" | pbcopy

# full three-stage pipe with streaming output
( echo "summarize this README:"; cat README.md ) | starchild --stream | tee summary.md

# code review pattern — concatenate context + question upstream
( echo "review this diff, flag risky changes:"; git diff ) | starchild

注意点: 位置引数のプロンプトを渡すと、stdin は無視されます。 コンテキストと指示の両方を送るには、cat <file> | starchild "<question>" に頼るのではなく（これはファイルの内容を黙って破棄してしまいます）、 上流で ( echo "<question>"; cat <file> ) のように連結してください。

SOUL.md のヒント（推奨）

ユーザーが CLI キーを求めたときに LLM が適切なツールを選べるよう、 エージェントの SOUL.md に追加してください:

## Issuing CLI bundles for the user's own bots/scripts

When the user asks "give me a cli key" / "create a starchild bundle" /
"let me talk to you from my terminal", run:

  python3 skills/cli-bridge/scripts/cli_login.py --label "<inferred>"

This is a chat bridge only — it does NOT let you run commands on their
machine or touch their files. Two independent opt-in capabilities, each
granting local access — only add them when the user explicitly asks:

- `--enable-shell` → run commands ("run commands on my laptop", "use
  agent-shell", "organize my Downloads"). Remote command execution.
- `--enable-files` → read/write files ("save this to my laptop", "read my
  ~/notes.md"). Reads/writes files on their machine.

  python3 skills/cli-bridge/scripts/cli_login.py --label "<inferred>" --enable-shell
  python3 skills/cli-bridge/scripts/cli_login.py --label "<inferred>" --enable-files

Treat both as granting access to their machine — never add either by
default or "to be helpful". If they later want a capability, mint a new
bundle with the flag and have them revoke the old one.

Default the label to something like "untitled-YYYY-MM-DD" if the user
doesn't suggest one. Show them the resulting bundle and tell them how
to revoke: `cli-list` to find the code, then `cli-revoke sc_…`.

After pairing, mention they can also pipe into the CLI from their
shell — e.g. `echo "..." | starchild`, `starchild "..." | pbcopy`,
or `( echo "review:"; git diff ) | starchild`. Stdout is the reply
(pipe-safe), stderr is diagnostics. Note the gotcha: passing a
positional prompt makes stdin get ignored, so context + question
should be concatenated upstream.

## Driving a local app via MCP (agent-shell ≥ v0.5.32)

Once `--enable-shell` is granted and `agent-shell` is running, you can
also drive LOCAL apps (Blender, Godot, a local Figma-bridge,
computer-use, …) through stdio MCP servers. The agent-shell daemon IS
the MCP Host: it reads `~/.config/starchild/mcp-servers.toml`, spawns
the servers, and registers their tools as `mcp__<server>__<tool>` into
this conversation. No separate MCP client (Cursor/Claude Desktop) is
needed.

When the user asks "control Blender" / "use the local figma plugin" /
"drive my local <app> via MCP":
- Confirm `agent-shell` is connected (a `local_shell` call works).
- Add the server to `~/.config/starchild/mcp-servers.toml` (ABSOLUTE
  paths only — no `$HOME`, no `~`). The app's Settings → Local MCP
  Servers panel can do this too.
- Restart `agent-shell` (`starchild agent-shell-stop && starchild
  agent-shell`, or via the app's RestartBanner). This does NOT cut the
  chat — only `local_shell`/file-transfer pause for ~2s.
- After restart the `mcp__<server>__*` tools appear. If they don't,
  read the daemon log (`~/.starchild/sc-chatroom[-dev]/cli-shell/
  agent.log` — look for `mcp: <id> ready` or `mcp: failed to start
  <id>: <reason>`) via `local_shell`.
- For servers with a local app bridge (Blender's addon on
  127.0.0.1:9876), confirm that bridge is running too — the MCP server
  process can start but its tools error until the backend app is up.
- Prefer the `mcp__<server>__*` tools over opening a raw socket to the
  app's bridge. The MCP layer gives you schemas + validation; the raw
  bridge is a last-resort fallback.

Don't add a server the user didn't ask for — a local MCP server can
execute arbitrary code on their machine. See the "Local MCP servers via
agent-shell" section above for the full config format and per-backend
caveats (Blender two-part, Figma local-vs-remote, etc.).