React Devtools

agent-react-devtools

CLI that connects to a running React or React Native app via the React DevTools protocol and exposes the component tree, props, state, hooks, and profiling data in a token-efficient format.

Core Workflow

1. Ensure connection — check agent-react-devtools status. If the daemon is not running, start it with agent-react-devtools start. Use agent-react-devtools wait --connected to block until a React app connects. 2. Inspect — get the component tree, search for components, inspect props/state/hooks. 3. Profile — start profiling, trigger the interaction (or ask the user to), stop profiling, analyze results. 4. Act — use the data to fix the bug, optimize performance, or explain what's happening.

Essential Commands

Daemon

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

Component Inspection

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

Performance Profiling

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

Understanding the Output

Component Labels

Every component gets a stable label like @c1, @c2. Use these to reference components in follow-up commands:

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

Type abbreviations: fn = function, cls = class, host = DOM element, memo = React.memo, fRef = forwardRef, susp = Suspense, ctx = context.

Components with errors or warnings show annotations: ⚠2 = 2 warnings, ✗1 = 1 error. Use agent-react-devtools errors to list only affected components.

Inspected Component

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

ƒ = function value. Values over 60 chars are truncated.

Profiling Output

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

Render causes: props-changed, state-changed, hooks-changed, parent-rendered, force-update, first-mount.

When specific changed keys are available, a changed: suffix shows exactly which props, state keys, or hooks triggered the render (e.g. changed: props: onClick, className state: count hooks: #0).

Common Patterns

Wait for the app to connect after a reload

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

Use this after triggering a page reload or HMR update to avoid querying empty state.

Diagnose slow interactions

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

Then inspect the worst offenders with get component @cN and profile report @cN.

Browse a long timeline in chunks

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

Use profile commit <N> to drill into a specific commit once you spot a spike.

Find a component and check its state

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

Verify a fix worked

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

Using with agent-browser

When using agent-browser to drive the app while profiling or debugging, you must use headed mode (--headed). Headless Chromium does not execute ES module scripts the same way as a real browser, which prevents the devtools connect script from running properly.

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

Important Rules

• Labels reset when the app reloads or components unmount/remount. After a reload, use wait --connected then re-check with get tree or find.
• `status` first — if status shows 0 connected apps, the React app is not connected. The user may need to run npx agent-react-devtools init in their project first.
• Headed browser required — if using agent-browser, always use --headed mode. Headless Chromium does not properly load the devtools connect script.
• Profile while interacting — profiling only captures renders that happen between profile start and profile stop. Make sure the relevant interaction happens during that window.
• Use `--depth` on large trees — a deep tree can produce a lot of output. Start with --depth 3 or --depth 4 and go deeper only on the subtree you care about.

References

Command Reference

Daemon Management

agent-react-devtools start [--port N]

Start the background daemon. Default port: 8097. The daemon listens for WebSocket connections from React apps and IPC connections from the CLI. Auto-starts when you run any other command, so you rarely need this explicitly.

agent-react-devtools stop

Stop the daemon process. All connection state is lost.

agent-react-devtools status

Show daemon status: port, connected apps, component count, profiling state, uptime, and last connection event.

Output:

Daemon: running (port 8097)
Apps: 1 connected, 42 components
Last event: app connected 3s ago
Uptime: 120s

If profiling is active, shows Profiling: active.

agent-react-devtools wait --connected [--timeout S]

Block until at least one React app connects via WebSocket. Resolves immediately if already connected. Default timeout: 30s. Exits non-zero on timeout.

agent-react-devtools wait --component <name> [--timeout S]

Block until a component with the given display name appears in the tree. Uses exact name matching. Useful after a reload to wait for a specific part of the UI to render. Default timeout: 30s. Exits non-zero on timeout.

Component Inspection

agent-react-devtools get tree [--depth N]

Print the component hierarchy as an indented tree. Each node shows:

• Label (@c1, @c2, ...) — stable within a session, resets on app reload
• Type tag (fn, cls, host, memo, fRef, susp, ctx)
• Display name
• Key (if present)

Use --depth N to limit tree depth. Recommended for large apps.

agent-react-devtools get component <@cN | id>

Inspect a single component. Shows:

• props — all prop values (functions shown as ƒ, long values truncated at 60 chars)
• state — state values (class components and useState)
• hooks — all hooks with current values and sub-hooks

Accepts a label (@c5) or numeric React fiber ID.

agent-react-devtools find <name> [--exact]

Search components by display name. Default is case-insensitive substring match. Use --exact for exact match.

Returns a flat list of matching components with labels, types, and keys.

agent-react-devtools count

Count components by type. Output: 42 components (fn:25 host:12 memo:3 cls:2).

agent-react-devtools errors

List all components that have non-zero error or warning counts. React tracks console errors and warnings per component; this command surfaces them.

Output example:

@c5 [fn] Form ⚠2 ✗1
@c8 [fn] Input ✗3

⚠N = N warnings, ✗N = N errors. Returns "No components with errors or warnings" when everything is clean.

Error/warning annotations also appear in get tree, get component, and find output when counts are non-zero.

Profiling

agent-react-devtools profile start [name]

Start a profiling session. Optional name for identification. Only one session can be active at a time.

agent-react-devtools profile stop

Stop profiling and collect data from React. Shows a summary with duration, commit count, and top rendered components.

agent-react-devtools profile slow [--limit N]

Rank components by average render duration (slowest first). Default limit: 10.

Output columns: label, type tag, component name, avg duration, max duration, render count, all causes, changed keys.

agent-react-devtools profile rerenders [--limit N]

Rank components by render count (most re-renders first). Default limit: 10.

Output columns: label, type tag, component name, render count, all causes, changed keys.

agent-react-devtools profile report <@cN | id>

Detailed render report for a single component: render count, avg/max/total duration, all render causes, changed keys.

agent-react-devtools profile timeline [--limit N] [--offset N] [--sort duration|timeline]

Chronological list of React commits during the profiling session. Each entry: index, duration, component count. Default limit: 20.

The header shows how many commits were returned and the total: Commit timeline (showing 1–20 of 87):. When all commits fit, it shows Commit timeline (42 commits):.

Default order is chronological (timeline order). --sort duration re-orders entries by duration descending (most expensive first) before applying --limit — use this to find the heaviest commits. --sort timeline explicitly requests chronological order (same as the default).

--offset N skips the first N entries (after sorting). Use with --limit to page through commits or skip a known-good warm-up region.

agent-react-devtools profile commit <N | #N> [--limit N]

Detail for a specific commit by index. Shows per-component self/total duration, render causes, and changed keys.

agent-react-devtools profile export <file>

Export profiling data as a JSON file importable in the React DevTools Profiler tab. The file can also be used as input to profile diff. Requires an active or recently stopped profiling session.

agent-react-devtools profile diff <before.json> <after.json> [--limit N] [--threshold N]

Compare two exported profiling sessions and show regressed, improved, new, and removed components. Default threshold: 5% — changes below this percentage are not reported. Use --limit N to cap the number of components shown per category. Does not require the daemon to be running.

Changed Keys

When React DevTools reports which specific props, state keys, or hooks triggered a re-render, profiling commands append a changed: suffix:

changed: props: onClick, className  state: count  hooks: #0

Categories with no changes are omitted. Keys are deduplicated across commits in aggregate reports (profile slow, profile rerenders, profile report).

Setup

agent-react-devtools init [--dry-run]

Auto-detect the framework in the current directory and configure the devtools connection. Supports Vite, Next.js, CRA, and Expo/React Native.

Use --dry-run to preview changes without writing files.

Profiling Guide

Quick Start

agent-react-devtools profile start
# Trigger the slow interaction (type, click, navigate)
agent-react-devtools profile stop
agent-react-devtools profile slow --limit 5

Step-by-Step Workflow

1. Establish a Baseline

Before profiling, check the current state:

agent-react-devtools status          # Confirm app is connected
agent-react-devtools count           # How many components are mounted
agent-react-devtools get tree --depth 3  # Understand the structure

2. Profile the Interaction

Start profiling, then trigger the specific interaction the user reports as slow:

agent-react-devtools profile start "typing in search"

The user should perform the interaction now. If using agent-browser, you can drive the interaction programmatically.

agent-react-devtools profile stop

3. Identify Bottlenecks

Slowest components — which components take the most time per render:

agent-react-devtools profile slow --limit 5

Most re-rendered — which components render too often:

agent-react-devtools profile rerenders --limit 5

These two views complement each other:

• A component that renders 100 times at 0.1ms each = 10ms total (re-render problem)
• A component that renders 2 times at 50ms each = 100ms total (slow render problem)

4. Drill Into Specific Components

Once you identify a suspect, get its full render report:

agent-react-devtools profile report @c12

This shows all render causes and the specific changed keys (e.g. changed: props: onClick, className state: count). Use the changed keys to pinpoint exactly what to stabilize or investigate. Common patterns:

5. Inspect the Component

Read the component's current props and hooks to understand what's changing:

agent-react-devtools get component @c12

Look for:

• Function props (ƒ) — likely unstable references if not wrapped in useCallback
• Object/array props — likely new references if not wrapped in useMemo
• State that updates too frequently

6. Fix and Verify

After applying the fix, re-profile with the same interaction:

agent-react-devtools profile start "after fix"
# Same interaction
agent-react-devtools profile stop
agent-react-devtools profile slow --limit 5

Compare render counts and durations to confirm improvement.

Export and Diff Workflow

Export Profiling Data

After stopping a profiling session, export the data to a JSON file. This file can be imported into the React DevTools Profiler tab for visual analysis, or used as input to profile diff.

agent-react-devtools profile stop
agent-react-devtools profile export baseline.json

Compare Two Profiling Sessions

To identify regressions or verify improvements, export profiles before and after a change, then diff them:

# Before the change
agent-react-devtools profile start "before"
# ... interact with the app ...
agent-react-devtools profile stop
agent-react-devtools profile export before.json

# After the change
agent-react-devtools profile start "after"
# ... same interaction ...
agent-react-devtools profile stop
agent-react-devtools profile export after.json

# Compare
agent-react-devtools profile diff before.json after.json

The diff shows regressed, improved, new, and removed components. Use --threshold to adjust sensitivity (default: 5%) and --limit to cap the number of components per category.

Common Performance Issues

Cascading re-renders from context or lifted state

A parent component re-renders (e.g., from a timer or context change) and all children re-render because none use React.memo. Look for high re-render counts with parent-rendered cause.

Unstable prop references

Parent passes onClick={() => ...} or style={{...}} inline — creates new references every render, defeating memo(). The child shows props-changed as the cause even though the values are semantically identical. The changed: output tells you exactly which props are the culprits (e.g. changed: props: onClick, style).

Expensive computations without memoization

A component does heavy work (filtering, sorting, formatting) on every render. Shows up as high avg render time. Fix with useMemo.

State updates in effects causing render loops

An effect updates state on every render, causing unnecessary commit cycles. Look for unusually high commit counts in profile timeline.

Setup Guide

agent-react-devtools works with any React or React Native app. The init command auto-detects your framework and configures everything.

Auto Setup (Recommended)

cd your-react-app
npx agent-react-devtools init

This detects the framework and applies the minimal configuration needed.

Use --dry-run to preview changes without modifying files:

npx agent-react-devtools init --dry-run

Framework-Specific Details

Vite

init adds the Vite plugin to your config:

// vite.config.ts
import { reactDevtools } from "agent-react-devtools/vite";

export default defineConfig({
  plugins: [reactDevtools(), react()],
});

The plugin only runs in dev mode (vite dev). It injects the connect script before your app code loads. Zero app code changes needed.

Next.js (App Router)

init creates a client component that imports the connect script and adds it to your root layout:

// app/devtools.tsx
'use client';
import 'agent-react-devtools/connect';
export default function DevTools() { return null; }

Then imports it in app/layout.tsx.

Create React App

init prepends the import to src/index.tsx:

import 'agent-react-devtools/connect';

React Native / Expo

React Native apps auto-connect to the devtools WebSocket on port 8097 — no code changes needed.

agent-react-devtools start
npx react-native start
# or: npx expo start

For physical devices, reverse the port:

adb reverse tcp:8097 tcp:8097

Manual Setup

If init doesn't cover your setup, add this as the first import in your entry point:

import 'agent-react-devtools/connect';

The connect script is:

• SSR-safe — no-ops on the server
• Production-safe — tree-shaken in production builds
• Connects via WebSocket with a 2-second timeout

Verifying the Connection

agent-react-devtools status

Expected output when connected:

Daemon: running (port 8097)
Apps: 1 connected, 42 components

If Apps: 0 connected: 1. Check the app is running in dev mode 2. Check the console for WebSocket connection errors 3. Ensure no other DevTools instance is using port 8097 4. If using agent-browser, make sure you're using headed mode (--headed) — headless Chromium does not properly execute the devtools connect script

Using with agent-browser

When automating the browser with agent-browser, you must use headed mode. Headless Chromium handles ES module script execution differently, which prevents the connect script from installing the devtools hook before React loads.

# Headed mode is required for devtools to connect
agent-browser --session devtools --headed open http://localhost:5173/

# Verify connection
agent-react-devtools status