agent-react-devtools

React DevTools プロトコル経由で実行中の React または React Native アプリに接続し、コンポーネントツリー、props、state、hooks、およびプロファイリングデータをトークン効率的な形式で公開する CLI。

コアワークフロー

1. 接続の確認 — agent-react-devtools status で確認。デーモンが実行中でない場合は agent-react-devtools start で開始。agent-react-devtools wait --connected を使用して React アプリが接続されるまでブロック。
2. 検査 — コンポーネントツリーを取得、コンポーネント検索、props/state/hooks を検査。
3. プロファイリング — プロファイリング開始、操作をトリガー（またはユーザーに実行させる）、プロファイリング終了、結果を分析。
4. 実行 — データを使用してバグを修正、パフォーマンスを最適化、または何が起きているかを説明。

必須コマンド

デーモン

agent-react-devtools start              # デーモン開始（最初のコマンドで自動開始）
agent-react-devtools stop               # デーモン停止
agent-react-devtools status             # 接続状態、コンポーネント数、最後のイベントを確認
agent-react-devtools wait --connected   # React アプリが接続されるまでブロック
agent-react-devtools wait --component App # コンポーネントが表示されるまでブロック

コンポーネント検査

agent-react-devtools get tree           # 完全なコンポーネント階層（ラベル: @c1, @c2, ...）
agent-react-devtools get tree --depth 3 # 深さを制限
agent-react-devtools get component @c5  # 特定コンポーネントの props、state、hooks
agent-react-devtools find Button        # 表示名で検索（ファジー検索）
agent-react-devtools find Button --exact # 完全一致検索
agent-react-devtools count              # タイプ別カウント: fn, cls, host, memo, ...
agent-react-devtools errors             # エラーまたは警告があるコンポーネントを一覧表示

パフォーマンスプロファイリング

agent-react-devtools profile start              # 記録開始
agent-react-devtools profile stop               # 停止してデータ収集
agent-react-devtools profile slow               # 平均レンダリング時間が長いコンポーネント
agent-react-devtools profile slow --limit 10    # トップ 10
agent-react-devtools profile rerenders          # 最も再レンダリングされたコンポーネント
agent-react-devtools profile report @c5         # 1 つのコンポーネントの詳細レポート
agent-react-devtools profile timeline --limit 10                        # 最初の 10 コミット（--limit を使用; キャップなしは 300+ 行をダンプする可能性がある）
agent-react-devtools profile timeline --limit 10 --offset 10           # 次の 10 個（ページネーション）
agent-react-devtools profile timeline --sort duration --limit 5        # 最も時間がかかった上位 5 コミット
agent-react-devtools profile timeline --sort timeline --limit 5        # 明示的な時系列順（デフォルトと同じ）
agent-react-devtools profile commit 3           # コミット #3 の詳細
agent-react-devtools profile export profile.json # React DevTools Profiler JSON としてエクスポート
agent-react-devtools profile diff before.json after.json  # 2 つのエクスポートを比較

出力の理解

コンポーネントラベル

すべてのコンポーネントに @c1、@c2 のような安定したラベルが付きます。これらを後続のコマンドでコンポーネント参照に使用：

@c1 [fn] App
├─ @c2 [fn] Header
├─ @c3 [fn] TodoList
│  ├─ @c4 [fn] TodoItem key=1
│  └─ @c5 [fn] TodoItem key=2
└─ @c6 [host] div

タイプの略称: fn = function、cls = class、host = DOM 要素、memo = React.memo、fRef = forwardRef、susp = Suspense、ctx = context。

エラーまたは警告があるコンポーネントは注釈表示: ⚠2 = 2 つの警告、✗1 = 1 つのエラー。agent-react-devtools errors を使用して影響を受けたコンポーネントのみ一覧表示。

検査されたコンポーネント

@c3 [fn] TodoList
props:
  items: [{"id":1,"text":"Buy milk"},{"id":2,"text":"Walk dog"}]
  onDelete: ƒ
state:
  filter: "all"
hooks:
  useState: "all"
  useMemo: [...]
  useCallback: ƒ

ƒ = 関数値。60 文字を超える値は切り詰められます。

プロファイリング出力

Slowest (by avg render time):
  @c3 [fn] ExpensiveList  avg:12.3ms  max:18.1ms  renders:47  causes:props-changed  changed: props: items, filter
  @c4 [fn] TodoItem  avg:2.1ms  max:5.0ms  renders:94  causes:parent-rendered, props-changed  changed: props: onToggle

レンダリング原因: props-changed、state-changed、hooks-changed、parent-rendered、force-update、first-mount。

特定の変更されたキーが利用可能な場合、changed: サフィックスはレンダリングをトリガーした props、state キー、または hooks を正確に表示します（例: changed: props: onClick, className state: count hooks: #0）。

一般的なパターン

リロード後アプリの接続を待機

agent-react-devtools wait --connected --timeout 10
agent-react-devtools get tree

ページリロードまたは HMR 更新をトリガーした後、空の状態をクエリしないようにこれを使用。

遅い操作の診断

agent-react-devtools profile start
# ユーザーがアプリと操作（または agent-browser を使用して UI を操作）
agent-react-devtools profile stop
agent-react-devtools profile slow --limit 5
agent-react-devtools profile rerenders --limit 5

その後、get component @cN と profile report @cN で最も問題のあるコンポーネントを検査。

長いタイムラインをチャンク単位で参照

agent-react-devtools profile timeline --limit 20               # コミット 0–19
agent-react-devtools profile timeline --limit 20 --offset 20   # コミット 20–39
agent-react-devtools profile timeline --offset 30 --limit 10   # ウォームアップをスキップ、30–39 を表示

スパイクを発見したら profile commit <N> を使用して特定のコミットをドリルダウン。

コンポーネントを見つけて状態を確認

agent-react-devtools find SearchBar
agent-react-devtools get component @c12

修正が機能したか検証

agent-react-devtools profile start
# 操作を繰り返す
agent-react-devtools profile stop
agent-react-devtools profile slow --limit 5
# レンダリングカウントと期間を前回の実行と比較

agent-browser との使用

agent-browser を使用してプロファイリングまたはデバッグ中にアプリを操作する場合、ヘッドレスモードではなくヘッドレスモード (--headed) を使用する必須です。ヘッドレス Chromium は ES モジュールスクリプトを実際のブラウザと同じ方法で実行しません。これにより、devtools 接続スクリプトが正常に実行されません。

agent-browser --session devtools --headed open http://localhost:5173/
agent-react-devtools status  # 1 つの接続されたアプリを表示すべき

重要なルール

• ラベルはリセット — アプリがリロードされるか、コンポーネントがアンマウント/リマウントされるとき。リロード後、wait --connected を使用してから get tree または find で再確認。
• 最初に status — status が 0 の接続されたアプリを表示する場合、React アプリは接続されていません。ユーザーは最初にプロジェクトで npx agent-react-devtools init を実行する必要があるかもしれません。
• ヘッドレスブラウザが必須 — agent-browser を使用する場合、常に --headed モードを使用。ヘッドレス Chromium は devtools 接続スクリプトを正しく読み込みません。
• 操作中にプロファイリング — プロファイリングは profile start と profile stop の間で起きるレンダリングのみをキャプチャ。関連する操作がそのウィンドウ内で確実に起きるようにしてください。
• 大きなツリーで --depth を使用 — 深いツリーは大量の出力を生成できます。--depth 3 または --depth 4 から始めて、関心のあるサブツリーでのみ深くしてください。

参考資料

ファイル	読む時期
commands.md	すべてのフラグとエッジケースを含む完全なコマンドリファレンス
profiling-guide.md	ステップバイステップのプロファイリングワークフローと結果の解釈
setup.md	異なるフレームワーク（Vite、Next.js、Expo、CRA）を接続する方法