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

agent-react-devtools profile start [name]           # Begin a profiling session
agent-react-devtools profile stop                    # Stop and collect data
agent-react-devtools profile report <@c1 | id>      # Render report for a component
agent-react-devtools profile slow [--limit N]        # Slowest components by avg duration
agent-react-devtools profile rerenders [--limit N]   # Most re-rendered components
agent-react-devtools profile timeline [--limit N]    # Commit timeline
agent-react-devtools profile commit <N | #N> [--limit N]  # Single commit detail
agent-react-devtools profile export <file>               # Export as React DevTools Profiler JSON
agent-react-devtools profile diff <before.json> <after.json> [--limit N] [--threshold N]  # Compare two exports

Connecting Your App

Quick setup

Run the init command in your project root to auto-configure your framework:

npx agent-react-devtools init

This detects your framework (Vite, Next.js, CRA) and patches the appropriate config file.

To undo these changes:

npx agent-react-devtools uninit

One-line import

Add a single import as the first line of your entry point (e.g. src/main.tsx):

import "agent-react-devtools/connect";

This handles everything: deleting the Vite hook stub, initializing react-devtools-core, and connecting via WebSocket. Your app is never blocked — if the daemon isn't running, it times out after 2 seconds.

Vite plugin

For Vite apps, use the plugin instead — no changes to your app code needed:

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

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

The plugin only runs in dev mode (vite dev), not in production builds.

Options:

reactDevtools({ port: 8097, host: "localhost" });

React Native

React Native apps connect to DevTools automatically — no code changes needed:

agent-react-devtools start
npx react-native start

For physical devices, forward the port:

adb reverse tcp:8097 tcp:8097

For Expo, the connection works automatically with the Expo dev client.

To use a custom port, set the REACT_DEVTOOLS_PORT environment variable.

Using with agent-browser

When using agent-browser to drive the app (e.g. for profiling interactions), you must use headed mode. Headless Chromium does not properly execute the devtools connect script:

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

Using with AI Coding Assistants

Add the skill to your AI coding assistant for richer context:

npx skills add callstackincubator/agent-react-devtools

This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf.

Claude Code plugin

You can also install via the Claude Code plugin marketplace:

/plugin marketplace add callstackincubator/agent-react-devtools
/plugin install agent-react-devtools@piotrski

Codex

Codex discovers project skills from AGENTS.md. This repo includes one at the root that registers:

packages/agent-react-devtools/skills/react-devtools/SKILL.md

Manual setup

If your assistant does not auto-load skills, add something like this to your project's AGENTS.md, CLAUDE.md, or equivalent agent instructions:

## React Debugging

This project uses agent-react-devtools to inspect the running React app.

- `agent-react-devtools start` — start the daemon
- `agent-react-devtools status` — check if the app is connected
- `agent-react-devtools get tree` — see the component hierarchy
- `agent-react-devtools get tree @c5` — see subtree from a specific component
- `agent-react-devtools get component @c1` — inspect a specific component
- `agent-react-devtools find <Name>` — search for components
- `agent-react-devtools errors` — list components with errors or warnings
- `agent-react-devtools profile start` / `profile stop` / `profile slow` — diagnose render performance

Development

bun install        # Install dependencies
bun run build      # Build
bun run test       # Run tests
bun run typecheck  # Type check

License

MIT

react-devtools