react-devtools

agent-react-devtools

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

基本的なワークフロー

1. 接続を確認する — agent-react-devtools status を実行します。デーモンが起動していない場合は、agent-react-devtools start で起動します。React アプリが接続するまで待機するには、agent-react-devtools wait --connected を使用します。
2. 調査する — コンポーネントツリーの取得、コンポーネントの検索、props/state/フックの調査を行います。
3. プロファイリングする — プロファイリングを開始し、操作を実行（またはユーザーに依頼）してから、プロファイリングを停止し、結果を分析します。
4. 対処する — データを利用して、バグの修正、パフォーマンスの最適化、または状況の説明を行います。

基本コマンド

デーモン

agent-react-devtools start              # Start daemon (auto-starts on first command)
agent-react-devtools stop               # Stop daemon
agent-react-devtools status             # Check connection, component count, last event
agent-react-devtools wait --connected   # Block until a React app connects
agent-react-devtools wait --component App # Block until a component appears

コンポーネントの調査

agent-react-devtools get tree           # Full component hierarchy (labels: @c1, @c2, ...)
agent-react-devtools get tree --depth 3 # Limit depth
agent-react-devtools get component @c5  # Props, state, hooks for a specific component
agent-react-devtools find Button        # Search by display name (fuzzy)
agent-react-devtools find Button --exact # Exact match
agent-react-devtools count              # Count by type: fn, cls, host, memo, ...
agent-react-devtools errors             # List components with errors or warnings

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

agent-react-devtools profile start              # Start recording
agent-react-devtools profile stop               # Stop and collect data
agent-react-devtools profile slow               # Slowest components by avg render time
agent-react-devtools profile slow --limit 10    # Top 10
agent-react-devtools profile rerenders          # Most re-rendered components
agent-react-devtools profile report @c5         # Detailed report for one component
agent-react-devtools profile timeline --limit 10                        # First 10 commits (use --limit; uncapped can dump 300+ lines)
agent-react-devtools profile timeline --limit 10 --offset 10           # Next 10 (pagination)
agent-react-devtools profile timeline --sort duration --limit 5        # Top 5 most expensive commits
agent-react-devtools profile timeline --sort timeline --limit 5        # Explicit chronological order (same as default)
agent-react-devtools profile commit 3           # Detail for commit #3
agent-react-devtools profile export profile.json # Export as React DevTools Profiler JSON
agent-react-devtools profile diff before.json after.json  # Compare two exports

出力の読み方

コンポーネントラベル

各コンポーネントには、@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 = 関数、cls = クラス、host = DOM 要素、memo = React.memo、fRef = forwardRef、susp = Suspense、ctx = コンテキスト。

エラーや警告のあるコンポーネントには注釈が表示されます：⚠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 キー、またはフックが具体的に表示されます（例：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
# User interacts with the app (or use agent-browser to drive the 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               # commits 0–19
agent-react-devtools profile timeline --limit 20 --offset 20   # commits 20–39
agent-react-devtools profile timeline --offset 30 --limit 10   # skip warm-up, show 30–39

急増箇所を見つけたら、profile commit <N> を使って特定のコミットを詳しく調査します。

コンポーネントを見つけて state を確認する

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

修正が機能したことを確認する

agent-react-devtools profile start
# Repeat the interaction
agent-react-devtools profile stop
agent-react-devtools profile slow --limit 5
# Compare render counts and durations to the previous run

agent-browser との併用

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

agent-browser --session devtools --headed open http://localhost:5173/
agent-react-devtools status  # Should show 1 connected app

重要なルール

• ラベルはリセットされます — アプリの再読み込み時、またはコンポーネントのアンマウント／再マウント時にリセットされます。再読み込み後は、wait --connected を実行してから、get tree または find で再確認してください。
• まず status を実行します — status に接続済みアプリが 0 と表示される場合、React アプリは接続されていません。Web ユーザーは npx agent-react-devtools init の実行が必要な場合があります。React Native ユーザーは setup.md に記載された 2 つの手動手順が必要です。この状態では、ツリーの観察コマンドは No React app is attached とともに終了コード 1 で終了します。これを正常な結果ではなく、「何も観察されなかった」として扱ってください。
• 別の DevTools が接続すると ID が再割り当てされます — React Native DevTools（または別のエージェント）が同じアプリに接続すると、React は新しい ID でツリーを再フラッシュし、デーモンは保存しているコピーを置き換えます。以前の @cN ラベルを再利用する前に、get tree または find を再実行してください。
• headed ブラウザーが必要です — 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）の接続方法