piotrski

agent-react-devtools

Give your AI agent eyes into your React app. Inspect component trees, read props and state, and profile rendering performance — all from the command line. Inspired by Vercel's agent-browser and Callstack's agent-device.

The project is in early development and considered experimental. Pull requests are welcome!

Features

• Walk the full component tree with props, state, and hooks
• Search for components by display name
• Profile renders: find slow components, excessive re-renders, and commit timelines
• Persistent background daemon that survives across CLI calls
• Token-efficient output built for LLM consumption

Install

npm install -g agent-react-devtools

Or run it directly:

npx agent-react-devtools start

Quick Start

agent-react-devtools start
agent-react-devtools status

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

Browse the component tree:

agent-react-devtools get tree --depth 3

@c1 [fn] App
├─ @c2 [fn] Header
│  ├─ @c3 [fn] Nav
│  └─ @c4 [fn] SearchBar
├─ @c5 [fn] TodoList
│  ├─ @c6 [fn] TodoItem key=1
│  ├─ @c7 [fn] TodoItem key=2
│  ├─ @c8 [fn] TodoItem key=3
│  └─ ... +47 more TodoItem
└─ @c9 [fn] Footer
53 components shown (1,843 total)

Host components (<div>, <span>, etc.) are filtered by default to keep output compact. Use --all to include them. Host components with keys or custom element names (e.g. <my-widget>) are always shown.

View a subtree rooted at a specific component:

agent-react-devtools get tree @c5 --depth 2

@c1 [fn] TodoList
├─ @c2 [fn] TodoItem key=1
├─ @c3 [fn] TodoItem key=2
└─ @c4 [fn] TodoItem key=3

Inspect a component's props, state, and hooks:

agent-react-devtools get component @c6

@c6 [fn] TodoItem key=1
props:
  id: 1
  text: "Buy groceries"
  done: false
  onToggle: ƒ
hooks:
  State: false
  Callback: ƒ

Find components by name:

agent-react-devtools find TodoItem

@c6 [fn] TodoItem key=1
@c7 [fn] TodoItem key=2
@c8 [fn] TodoItem key=3

Profile rendering performance:

agent-react-devtools profile start
# ... interact with the app ...
agent-react-devtools profile stop
agent-react-devtools profile slow

Slowest (by avg render time):
  @c5 [fn] TodoList  avg:4.2ms  max:8.1ms  renders:6  causes:props-changed  changed: props: items, onDelete
  @c4 [fn] SearchBar  avg:2.1ms  max:3.4ms  renders:12  causes:hooks-changed  changed: hooks: #0
  @c2 [fn] Header  avg:0.8ms  max:1.2ms  renders:3  causes:parent-rendered

Commands

Daemon

agent-react-devtools start [--port 8097]   # Start daemon
agent-react-devtools stop                   # Stop daemon
agent-react-devtools status                 # Connection status

Components

agent-react-devtools get tree [@c1 | id] [--depth N] [--all] [--max-lines N]  # Component hierarchy (subtree)
agent-react-devtools get component <@c1 | id>      # Props, state, hooks
agent-react-devtools find <name> [--exact]          # Search by display name
agent-react-devtools count                          # Component count by type
agent-react-devtools errors                         # Components with errors/warnings

Tree output flags:

• --depth N — limit tree depth
• --all — include host components (filtered by default)
• --max-lines N — hard cap on output lines

Components are labeled @c1, @c2, etc. You can use these labels or numeric IDs interchangeably.

Components with errors or warnings are annotated in tree and search output:

@c5 [fn] Form ⚠2 ✗1

Use the errors command to list only components with issues:

agent-react-devtools errors

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

Wait

Block until a condition is met. Useful in scripts or agent workflows where the daemon starts before the app:

agent-react-devtools wait --connected [--timeout 30]          # Block until an app connects
agent-react-devtools wait --component App [--timeout 30]      # Block until a component appears

Exits with code 0 when the condition is met, or code 1 on timeout.

Profiling