rn-devtools-hub

rn-devtools-hub

React Native 向けのエージェントランタイムです。エージェントは、React がアプリを見るのと同じようにアプリを認識し、各要素を生成したファイルを把握して、 座標に頼らず操作し、動作することを証明できます。依存関係はゼロで、テレメトリーや使用状況の カウントもありません。ローカルハブと SDK を備えています。

ドキュメント · クイックスタート · インテグレーション · コントリビューション

エージェントから利用する

どちらのプラグインも、MCP サーバーと、ツールを連携して使う方法をエージェントに教えるスキルをインストールします。解決不可能に見える問題をデバッグする前にプロジェクトのコンテキストを確認し、スクリーンショットではなくアサーションで結果を証明し、スリープではなくイベントを待ち、リポジトリを grep するのではなく要素のソースを読み取ります。

Claude Code

/plugin marketplace add rn-devtools-hub/rn-devtools-hub
/plugin install rn-devtools-hub

Codex

codex plugin marketplace add rn-devtools-hub/rn-devtools-hub
codex plugin add rn-devtools-hub

次に、アプリのルートでハブを起動します。エージェントはこのハブと通信します。

npx rn-devtools-hub

サーバーは手動で登録することもできます。Claude Code：

claude mcp add rn-devtools --transport http http://127.0.0.1:8973/mcp

Codex の場合は、~/.codex/config.toml に記述します。

[mcp_servers.rn-devtools]
url = "http://127.0.0.1:8973/mcp"

Cursor にはマーケットプレイスがないため、自分のプロジェクトに2つのファイルを用意します。.cursor/mcp.json でサーバーを宣言します。

{
  "mcpServers": {
    "rn-devtools": { "type": "http", "url": "http://127.0.0.1:8973/mcp" }
  }
}

そして、スキルに相当する Cursor のルールをコピーします。

mkdir -p .cursor/rules
cp node_modules/rn-devtools-hub/templates/cursor-rule.mdc \
   .cursor/rules/rn-devtools-hub.mdc

alwaysApply: false が設定されているため、Cursor はリクエストごとに適用するのではなく、タスクに該当するときにこのルールを読み込みます。

それ以外のエージェントでは、スキル単体を skills.sh レジストリからインストールできます。

npx skills add rn-devtools-hub/rn-devtools-hub

.agents/skills/rn-devtools-hub を作成し、Gemini CLI や Copilot から Windsurf、Zed まで、検出したエージェントにリンクします。インストールされるのはスキルだけなので、上記の手順でサーバーを登録し、ハブを起動して、エージェントが通信できるようにしてください。

stdio のみを使用するクライアントには、ハブへのブリッジとして npx rn-devtools-hub mcp を使います。必要に応じてハブも起動します。

テストやデバッグのタスクを開始すると、エージェントにはプロジェクト名とクリック可能なダッシュボード URL を知らせ、その後は自動的に作業を続けるよう指示されています。ハブは、別のプロジェクトがフォールバックポートを使用する場合も含め、実際に割り当てられたポートと現在のトークンを提供します。このリンクは、list_devices、get_project_context、session_start の dashboard フィールドからも利用できます。

スクリーンショット

概要：リクエスト数、エラー率、JS スレッドの遅延、接続、デバイスの状態をひと目で確認できます

ネットワーク：メソッドを色分けし、遅いリクエストを強調表示。JSON の折りたたみ、cURL としてコピー、デバイスから送信される前にシークレットを秘匿

ミラー：adb 経由でデバイスの画面をライブ表示。クリックでタップ、ドラッグでスワイプ、ホイールでスクロール。さらに「戻る」「ホーム」「最近使ったアプリ」「開発メニュー」を操作できます

ツール：エージェントの操作と、それに対するアプリの応答を確認できます。ツールごとの呼び出しを回答あり／空／失敗に分類し、メッセージごとに失敗をグループ化。ツールが提示した理由付きの空の回答と、各回答でエージェントに課金されるコンテキストも表示します

## 理由

SDK は、アプリの JavaScript ランタイム内で動作します。

SDK はアプリケーションコードと並行して直接実行されます。アプリ内にインストールされた API を通じて、React のツリーを読み取り、ハンドラーを呼び出し、リクエストを計測し、登録済みのストアにアクセスします。ハブは、デバッガープロトコルのセッションを必要とせず、独自のローカル接続を通じてこれらの機能を受け取ります。他のツールは CDP などのプロトコルを通じてランタイム内部にアクセスできますが、ハブの基盤となるのは、アプリ内に明示的に組み込まれた SDK とそのイベントコントラクトです。

この立ち位置を基盤として、プロダクト全体が構築されています。それ以外のすべては、ここから導かれます。

エージェントができること	ランタイム内にあるからこそ可能な理由
ロールとアクセシブルネームで要素を見つけて操作する	アクションはピクセルではなく、アプリ独自の props を通じて実行されます
要素を生成したファイルと行を取得する	位置情報は React の開発用管理情報にあります
スクリーンショットなしでステップを証明する	スクリーンショットでは、ひそかに失敗したリクエストを確認できません
古いネイティブビルドとコードの問題を見分ける	実際のバイナリが何かを知っているのはランタイムだけです
時計とネットワークを停止する	Date と fetch はランタイム内にあります
10 画面を順に進まず、アプリを正確な状態にする	ストアに直接アクセスできます
スコアを付けるだけでなく、ビジュアルリグレッションを説明する	変更された領域を、それを所有するコンポーネントまでたどれます

アプリ内で動作する純粋な JavaScript SDK（本番環境では非アクティブ）、単一プロセスで動作するローカルハブ、ブラウザー上のダッシュボード。ハブを含め、依存関係はどこにもありません。ハブはテレメトリーを収集しません。MCP の結果はエージェントに配信され、エージェントのモデルプロバイダーに送信される場合があります。設定されたストアプラグインは、宣言されているベンダーのエンドポイントに接続します。

機能

パネル	表示内容
Overview	KPI タイル、JS スレッドの遅延、HTTP ステータス、所要時間の分布
Crashes	致命的エラー、JS エラー、未処理の Promise 拒否、スタック
Network	リクエスト／レスポンスのインスペクター（色分けされたメソッド、所要時間、サイズ）、cURL としてコピー、シークレットをマスキング
Uploads	ライブアップロードキュー（アプリがイベントを出力する場合。プロトコルを参照）
Cache	React Query のスナップショット：キー、ステータス、鮮度、データ
Storage	AsyncStorage のキー、サイズ、値、書き込み時刻のライブ表示
Screens	ナビゲーションの履歴、画面ごとの滞在時間
Logs	console.log/info/warn/error、色分けされた JSON、フィルター
SQLite	アプリのデータベースに対する読み取り専用 SQL コンソール（SELECT/PRAGMA）
Endpoints	宣言されたエンドポイント、呼び出し、レイテンシーのマップ
Actions	アプリを操作するボタン：再読み込み、キャッシュの消去、カスタムアクション
Tests	人が読める .hubflow シナリオ、リプレイのライブ進捗、失敗の診断、承認済みの視覚的証拠、安全なターゲット修復候補
Tools	エージェントがこのハブで行う操作：ツールごとの呼び出し回数、メッセージ付きの失敗、空の回答とその理由、返されたコンテキストのバイト数（ピクセル数は別にカウント。セッションのコンテキストの大半をスクリーンショットに費やすのは、高コストな検証方法だからです）、使用されたセレクター、アプリ独自のイベントに対してリプレイされたループ
Plugins	アプリを取り巻くサービス：App Store Connect と Google Play、それぞれの設定、リリースを変更できるかどうか、接続するすべてのホスト
Design	アイコン、スプラッシュ、フォント、サウンド、アイデンティティ（app.json とアセットから読み取り）
Mirror	アプリ画面のライブ表示（アプリに react-native-view-shot が必要）、adb 経由の Android 全体（タップ、スワイプ、キーボード、Wi-Fi）、xcrun 経由の iOS シミュレーター

Overview パネルを開くと、プロジェクトのコンテキストが表示されます。プロジェクトが宣言している内容、アプリが実際に実行している内容、そして両者の食い違いです。ここで午後を丸ごと無駄にする最も一般的な原因は、古いネイティブビルドです。コードを読み始める前に、そのことが示されます。

さらに、複数デバイスのセッション統合、バグレポートの Markdown エクスポート（GitHub の Issue にそのまま使用可能）、リアルタイムの機能バッジ、Claude、Cursor、または任意の MCP クライアントからすべてを操作するためのローカル MCP サーバーを利用できます。

Hubflow scenarios を参照して、操作を記録し、実行時の回帰テストとして保存し、CI でリプレイし、ダッシュボードで選択された成功または失敗のスクリーンショットを確認してください。

エージェントが得られるもの

ツール	回答できる内容
get_project_context	プロジェクトで宣言されている内容、実際に実行される内容、およびその矛盾点です。何かがあり得ない動作をした場合は、まずこれを呼び出してください
get_ui_tree、query_ui	表示中のコンポーネントと、それぞれを生成したソースファイルおよび行番号です
ui_act	要素を指定してタップ、入力、送信、スクロールを行います。ピクセルでの指定は使いません
assert	ステップを検証します。要素の種類を指定すると再試行し、イベントの種類を指定すると、失敗が通知されなかったリクエスト、コンソールエラー、未処理の拒否を検出します
freeze_time、mock_network	JS レベルで動作を決定論的にし、シナリオを二度実行しても同じ結果にします
get_state、set_state	画面を十個も遷移せずに、アプリを正確な状態に設定します
render_component	実行中のアプリ内で、実際のプロバイダーの下にコンポーネントをマウントします
snapshot_baseline、compare_snapshot	変更された領域を所有するコンポーネントを示すビジュアル差分です
export_session、export_flow	相関付けられた単一のタイムラインと、アクションおよびそれによって生じた結果です
save_flow、list_flows、get_flow、run_flow、propose_flow_repair	実行時シナリオを保存し、アサーションとスクリーンショット付きで再生します。また、対象が明確に特定されている場合に、その位置が変わるとレビュー可能な修復候補を作成します
audit_accessibility	React がレンダリングしているものの、アクセシビリティツリーに公開されていない内容です
list_plugins、asc_*、gplay_*	アプリのリリース状況を確認できます。ビルドの処理は完了したか、審査中のバージョンはどこにあるか、本番環境では何が配信されているか、ストアレビューには何が書かれているかを確認できます。また、TestFlight への配布、審査への提出、トラックの昇格、段階的なロールアウトの拡大や停止も実行できます
capture_store_screenshots	実行中のアプリから App Store と Play のスクリーンショットを再生成します。マニフェストで指定したデバイス、ロケール、画面に対し、それぞれアプリ独自の開発アクションで移動し、ネイティブ解像度でキャプチャしてアップロードします。ピクセルがエージェントのコンテキストに入ることはありません

React 19 でもソース位置は維持されます。位置がバンドル内を指すオーナースタックに記録される場合、エージェントが確認する前にハブが Metro を使ってシンボルを解決します。

AI エージェント向けに、ハブは MCP 経由の実行時 UI 自動化も提供します。get_ui_tree（React ランタイムから読み取った、表示中のコンポーネントのセマンティックツリー。マップなど、アクセシビリティ情報のないネイティブビューも含みます）、query_ui（within で範囲を指定し、ロールとアクセシブル名、testID、プレースホルダー、テキスト、ラベルで要素を検索。測定済みの矩形も取得します）、ui_act（要素を指定してタップ、正確なテキストの入力、送信、スクロールを行い、ピクセルは使いません。また、入力欄の値を読み返してテキストが反映されたかを確認します）、型付き開発アクション（list_actions／run_action：UI に触れずに画面遷移、データのシード、ログインを実行）、相関付けられたイベントフロー（wait_for_event、get_events_since：スリープを screen.ready などの実際のシグナルに置き換えます）を利用できます。Expo Go、開発ビルド、ベア React Native で動作し、シミュレーターのない CI でも使えます。devtools.attachUiAutomation() で有効にしてください。

ハブはネイティブ層にも対応しており、エージェント向けの idb／simctl スクリプト機能をすべて包含します。session_start は適切な Metro サーバー上で開発ビルドをダイアログなしで起動します（権限は事前に許可され、開発メニューのオンボーディングはスキップされます）。さらに、iOS シミュレーターと Android デバイスで、set_permission、launch_app、open_url、screenshot_native、set_location、send_push、set_appearance、set_animations、set_overlay（expo-dev-menu のバブルは、UI ツリーに表示できないネイティブコントロールを覆います）、そして最終手段の tap_native と swipe_native を利用できます。すべての機能はプローブされ、使えない場合は適切に縮退します。

ここまでの機能はすべてマシン上で完結します。リリースの残り半分はプラグインが担います。App Store Connect と Google Play はハブに同梱されていますが、認証情報を与えるまで動作しません。これらはリリース情報を読み取るだけでなく、リリース操作も実行します。そのため、ロールアウトの拡大を判断するエージェントは、その判断に必要なクラッシュの証拠をすでに確認しているエージェントでもあります。ハブのプラグインをインストールするとリリーススキルも一緒にインストールされるため、ほかに追加するものはありません。 設定済みのプラグインは、起動時に接続先のホストを表示します。未設定のプラグインはツールを一切公開しないため、エージェントが使えないツールでコンテキストを消費することはありません。また、RN_DEVTOOLS_PLUGIN_WRITES=off を指定すると、何かを変更できるツールがすべて削除されます。docs/plugins.md を参照してください。

クイックスタート

前提条件：Node 20 以降。Bun は利用可能な場合に使用されますが、必須ではありません。オプション機能（adb ミラー、iOS シミュレーター、Wi-Fi）にはそれぞれ前提条件があります。詳しくは、機能別の前提条件を参照してください。

# 1. In your React Native / Expo project, as a devDependency:
npm install --save-dev rn-devtools-hub

# 2. Wire it up automatically (detects your libraries, writes the glue,
#    hooks the entry point, adds the `devtools` script):
npx rn-devtools-hub init

# 3. Start the hub (runs on Bun or Node 20+)
npm run devtools
# -> Dashboard: http://localhost:8973/?token=... (URL printed at startup)

init はプロジェクトを調査し、実際に実行できるコードだけを生成します。axios を使用している場合は axios のインターセプト、AsyncStorage がある場合は Storage パネル、expo-device がある場合はデバイス情報などを生成します。既存のグルーコードファイルを上書きすることはありません（--force を使用してください）。--dry-run を指定すると、変更内容を確認できます。

これで完了です。ログ、クラッシュ、パフォーマンス情報はすでに取り込まれます。追加のインテグレーション（ネットワーク、キャッシュ、ストレージ、SQLite、ミラーなど）は、数行で設定できます。インテグレーションガイドを参照してください。

インテグレーションガイド

SDK は特定のライブラリに依存せず、任意のライブラリに接続できる汎用プリミティブを公開します。すべてのレシピはdocs/integration.mdに記載されています。特に次の項目を参照してください。

• devtools.attachAxios(instance, "api")：任意の axios インスタンス
• devtools.wrapFetch(fetch, "uploads")：任意の fetch ベースのクライアント
• devtools.emit(type, payload)：任意のパネルにデータを送信
• devtools.onCommand(name, handler)：ダッシュボードからのコマンドに応答（例：SQLite）
• devtools.registerAction({name, label, danger, requiresNative}, handler)
• devtools.attachUiAutomation()：AI エージェント向けの UI 認識と操作
• devtools.markScreenReady("Login")：エージェントが待機する「画面準備完了」シグナル
• イベントとコマンドの完全なプロトコル：docs/protocol.md。これは契約です。ツール（または LLM）は、これを実装することでパネルを統合できます。

ホストプロジェクトの依存関係

SDK による制約は一切ありません。必要な機能に応じて、利用するプロジェクトに次のものを追加してください。

機能	プロジェクトにインストールするもの	種類
パッケージ本体	rn-devtools-hub	devDependencies
アプリのミラー（画面ストリーム）	react-native-view-shot	dependencies（Expo Go に含まれています）
Storage パネル	@react-native-async-storage/async-storage	ほとんどのアプリにすでに存在します
SQLite コンソール	expo-sqlite（またはドライバーと sqlite.query ハンドラー）	アプリによって異なります
拡張デバイス情報	expo-device、expo-application、expo-network	dependencies
Android の完全なミラー	開発マシン上の adb（アプリ内には不要）	システムツール
iOS シミュレーターのミラー	Xcode コマンドラインツール（開発マシン）	システムツール

セキュリティ

• SDK は __DEV__ の外では動作しません（あなたの側と SDK 側の二重ガード）
• ダッシュボードにはトークンが必要です（起動時に表示されます。固定するには RN_DEVTOOLS_TOKEN を指定してください）
• 機密性の高いヘッダー（Authorization、Cookie、x-api-key）は、デバイスから送信される前にマスキングされます
• SQLite コンソールで受け付けるのは SELECT と PRAGMA のみです
• MCP サーバーは localhost でのみリッスンし、Origin を検証します
• Design パネルのアセットはプロジェクトルート内に限定され、拡張子もホワイトリストで制限されます
• プラグインは唯一の外向き通信経路です。認証情報がなければ動作せず、それぞれが接続先のホストを宣言します。また、認証情報がツールから返されたり、ログに書き込まれたりすることはありません
• 何かを変更するプラグインツールはすべて、その旨が宣言され、MCP クライアントが確認できるよう注記されています。また、RN_DEVTOOLS_PLUGIN_WRITES=off ですべて削除できます
• RN_DEVTOOLS_SCREENSHOTS=off（または数値）を指定すると、ピクセルキャプチャを無効化または制限できます。スクリーンショットによるエージェントの検証を望まないチーム向けです

貢献

貢献を歓迎します。詳しいガイドは CONTRIBUTING.mdをご覧ください。要点は次のとおりです。

git clone https://github.com/rn-devtools-hub/rn-devtools-hub
cd rn-devtools-hub
npm install          # also installs the husky hooks
npm test             # vitest
npm run typecheck
npm run hub          # starts the local hub to test the dashboard

• コミットにはConventional Commits （feat:、fix:、docs:など）に従ってください。これらに基づいて、変更履歴とバージョンが 自動的に生成されます（release-it）。また、コミット時にcommitlintがチェックします。
• コミット前フックで型チェックとテストが実行されます。
• リリース：npm run release（メンテナー）

AI エージェントは、AGENTS.mdとllms.txtをお読みください。

ライセンス

MIT