SKILL.md

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

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.

Inspect — get the component tree, search for components, inspect props/state/hooks.

Profile — start profiling, trigger the interaction (or ask the user to), stop profiling, analyze results.

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

File

When to read

commands.md

Full command reference with all flags and edge cases

profiling-guide.md

Step-by-step profiling workflows and interpreting results

setup.md

How to connect different frameworks (Vite, Next.js, Expo, CRA)

react-devtools