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