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!
- 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
npm install -g agent-react-devtoolsOr run it directly:
npx agent-react-devtools startagent-react-devtools start
agent-react-devtools statusDaemon: 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
ββ @c9 [fn] Footer
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 slowSlowest (by avg render time):
@c5 [fn] TodoList avg:4.2ms max:8.1ms renders:6 causes:props-changed
@c4 [fn] SearchBar avg:2.1ms max:3.4ms renders:12 causes:hooks-changed
@c2 [fn] Header avg:0.8ms max:1.2ms renders:3 causes:parent-rendered
agent-react-devtools start [--port 8097] # Start daemon
agent-react-devtools stop # Stop daemon
agent-react-devtools status # Connection statusagent-react-devtools get tree [--depth N] # Component hierarchy
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 typeComponents are labeled @c1, @c2, etc. You can use these labels or numeric IDs interchangeably.
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 appearsExits with code 0 when the condition is met, or code 1 on timeout.
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 detailRun the init command in your project root to auto-configure your framework:
npx agent-react-devtools initThis detects your framework (Vite, Next.js, CRA) and patches the appropriate config file.
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.
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 apps connect to DevTools automatically β no code changes needed:
agent-react-devtools start
npx react-native startFor physical devices, forward the port:
adb reverse tcp:8097 tcp:8097For Expo, the connection works automatically with the Expo dev client.
To use a custom port, set the REACT_DEVTOOLS_PORT environment variable.
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"Add the skill to your AI coding assistant for richer context:
npx skills add piotrski/agent-react-devtoolsThis works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf.
You can also install via the Claude Code plugin marketplace:
/plugin marketplace add piotrski/agent-react-devtools
/plugin install agent-react-devtools@piotrski
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
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 component @c1` β inspect a specific component
- `agent-react-devtools find <Name>` β search for components
- `agent-react-devtools profile start` / `profile stop` / `profile slow` β diagnose render performancebun install # Install dependencies
bun run build # Build
bun run test # Run tests
bun run typecheck # Type checkMIT