{
  "markdown": "# agent-react-devtools\n\nGive 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](https://github.com/vercel-labs/agent-browser) and Callstack's [agent-device](https://github.com/callstackincubator/agent-device).\n\nThe project is in early development and considered experimental. Pull requests are welcome!\n\n## Features\n\n- Walk the full component tree with props, state, and hooks\n- Search for components by display name\n- Profile renders: find slow components, excessive re-renders, and commit timelines\n- Persistent background daemon that survives across CLI calls\n- Token-efficient output built for LLM consumption\n\n## Install\n\n```sh\nnpm install -g agent-react-devtools\n```\n\nOr run it directly:\n\n```sh\nnpx agent-react-devtools start\n```\n\n## Quick Start\n\n```sh\nagent-react-devtools start\nagent-react-devtools status\n```\n\n```\nDaemon: running (port 8097)\nApps: 1 connected, 24 components\nUptime: 12s\nLast event: app connected 3s ago\n```\n\nBrowse the component tree:\n\n```sh\nagent-react-devtools get tree --depth 3\n```\n\n```\n@c1 [fn] App\n├─ @c2 [fn] Header\n│  ├─ @c3 [fn] Nav\n│  └─ @c4 [fn] SearchBar\n├─ @c5 [fn] TodoList\n│  ├─ @c6 [fn] TodoItem key=1\n│  ├─ @c7 [fn] TodoItem key=2\n│  ├─ @c8 [fn] TodoItem key=3\n│  └─ ... +47 more TodoItem\n└─ @c9 [fn] Footer\n53 components shown (1,843 total)\n```\n\nHost 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.\n\nView a subtree rooted at a specific component:\n\n```sh\nagent-react-devtools get tree @c5 --depth 2\n```\n\n```\n@c1 [fn] TodoList\n├─ @c2 [fn] TodoItem key=1\n├─ @c3 [fn] TodoItem key=2\n└─ @c4 [fn] TodoItem key=3\n```\n\nInspect a component's props, state, and hooks:\n\n```sh\nagent-react-devtools get component @c6\n```\n\n```\n@c6 [fn] TodoItem key=1\nprops:\n  id: 1\n  text: \"Buy groceries\"\n  done: false\n  onToggle: ƒ\nhooks:\n  State: false\n  Callback: ƒ\n```\n\nFind components by name:\n\n```sh\nagent-react-devtools find TodoItem\n```\n\n```\n@c6 [fn] TodoItem key=1\n@c7 [fn] TodoItem key=2\n@c8 [fn] TodoItem key=3\n```\n\nProfile rendering performance:\n\n```sh\nagent-react-devtools profile start\n# ... interact with the app ...\nagent-react-devtools profile stop\nagent-react-devtools profile slow\n```\n\n```\nSlowest (by avg render time):\n  @c5 [fn] TodoList  avg:4.2ms  max:8.1ms  renders:6  causes:props-changed  changed: props: items, onDelete\n  @c4 [fn] SearchBar  avg:2.1ms  max:3.4ms  renders:12  causes:hooks-changed  changed: hooks: #0\n  @c2 [fn] Header  avg:0.8ms  max:1.2ms  renders:3  causes:parent-rendered\n```\n\n## Commands\n\n### Daemon\n\n```sh\nagent-react-devtools start [--port 8097]   # Start daemon\nagent-react-devtools stop                   # Stop daemon\nagent-react-devtools status                 # Connection status\n```\n\n### Components\n\n```sh\nagent-react-devtools get tree [@c1 | id] [--depth N] [--all] [--max-lines N]  # Component hierarchy (subtree)\nagent-react-devtools get component <@c1 | id>      # Props, state, hooks\nagent-react-devtools find <name> [--exact]          # Search by display name\nagent-react-devtools count                          # Component count by type\nagent-react-devtools errors                         # Components with errors/warnings\n```\n\nTree output flags:\n- `--depth N` — limit tree depth\n- `--all` — include host components (filtered by default)\n- `--max-lines N` — hard cap on output lines\n\nComponents are labeled `@c1`, `@c2`, etc. You can use these labels or numeric IDs interchangeably.\n\nComponents with errors or warnings are annotated in tree and search output:\n\n```\n@c5 [fn] Form ⚠2 ✗1\n```\n\nUse the `errors` command to list only components with issues:\n\n```sh\nagent-react-devtools errors\n```\n\n```\n@c5 [fn] Form ⚠2 ✗1\n@c8 [fn] Input ✗3\n```\n\n### Wait\n\nBlock until a condition is met. Useful in scripts or agent workflows where the daemon starts before the app:\n\n```sh\nagent-react-devtools wait --connected [--timeout 30]          # Block until an app connects\nagent-react-devtools wait --component App [--timeout 30]      # Block until a component appears\n```\n\nExits with code 0 when the condition is met, or code 1 on timeout.\n\n### Profiling\n\n```sh\nagent-react-devtools profile start [name]           # Begin a profiling session\nagent-react-devtools profile stop                    # Stop and collect data\nagent-react-devtools profile report <@c1 | id>      # Render report for a component\nagent-react-devtools profile slow [--limit N]        # Slowest components by avg duration\nagent-react-devtools profile rerenders [--limit N]   # Most re-rendered components\nagent-react-devtools profile timeline [--limit N]    # Commit timeline\nagent-react-devtools profile commit <N | #N> [--limit N]  # Single commit detail\nagent-react-devtools profile export <file>               # Export as React DevTools Profiler JSON\nagent-react-devtools profile diff <before.json> <after.json> [--limit N] [--threshold N]  # Compare two exports\n```\n\n## Connecting Your App\n\n### Quick setup\n\nRun the init command in your project root to auto-configure your framework:\n\n```sh\nnpx agent-react-devtools init\n```\n\nThis detects your framework (Vite, Next.js, CRA) and patches the appropriate config file.\n\nTo undo these changes:\n\n```sh\nnpx agent-react-devtools uninit\n```\n\n### One-line import\n\nAdd a single import as the first line of your entry point (e.g. `src/main.tsx`):\n\n```ts\nimport \"agent-react-devtools/connect\";\n```\n\nThis 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.\n\n### Vite plugin\n\nFor Vite apps, use the plugin instead — no changes to your app code needed:\n\n```ts\n// vite.config.ts\nimport { defineConfig } from \"vite\";\nimport react from \"@vitejs/plugin-react\";\nimport { reactDevtools } from \"agent-react-devtools/vite\";\n\nexport default defineConfig({\n  plugins: [reactDevtools(), react()],\n});\n```\n\nThe plugin only runs in dev mode (`vite dev`), not in production builds.\n\nOptions:\n\n```ts\nreactDevtools({ port: 8097, host: \"localhost\" });\n```\n\n### React Native\n\nReact Native apps connect to DevTools automatically — no code changes needed:\n\n```sh\nagent-react-devtools start\nnpx react-native start\n```\n\nFor physical devices, forward the port:\n\n```sh\nadb reverse tcp:8097 tcp:8097\n```\n\nFor Expo, the connection works automatically with the Expo dev client.\n\nTo use a custom port, set the `REACT_DEVTOOLS_PORT` environment variable.\n\n## Using with agent-browser\n\nWhen 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:\n\n```sh\nagent-browser --session devtools --headed open http://localhost:5173/\nagent-react-devtools status  # Should show \"Apps: 1 connected\"\n```\n\n## Using with AI Coding Assistants\n\nAdd the skill to your AI coding assistant for richer context:\n\n```sh\nnpx skills add callstackincubator/agent-react-devtools\n```\n\nThis works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf.\n\n### Claude Code plugin\n\nYou can also install via the Claude Code plugin marketplace:\n\n```\n/plugin marketplace add callstackincubator/agent-react-devtools\n/plugin install agent-react-devtools@piotrski\n```\n\n### Codex\n\nCodex discovers project skills from `AGENTS.md`. This repo includes one at the root that registers:\n\n- `packages/agent-react-devtools/skills/react-devtools/SKILL.md`\n\n### Manual setup\n\nIf your assistant does not auto-load skills, add something like this to your project's `AGENTS.md`, `CLAUDE.md`, or equivalent agent instructions:\n\n```markdown\n## React Debugging\n\nThis project uses agent-react-devtools to inspect the running React app.\n\n- `agent-react-devtools start` — start the daemon\n- `agent-react-devtools status` — check if the app is connected\n- `agent-react-devtools get tree` — see the component hierarchy\n- `agent-react-devtools get tree @c5` — see subtree from a specific component\n- `agent-react-devtools get component @c1` — inspect a specific component\n- `agent-react-devtools find <Name>` — search for components\n- `agent-react-devtools errors` — list components with errors or warnings\n- `agent-react-devtools profile start` / `profile stop` / `profile slow` — diagnose render performance\n```\n\n## Development\n\n```sh\nbun install        # Install dependencies\nbun run build      # Build\nbun run test       # Run tests\nbun run typecheck  # Type check\n```\n\n## License\n\nMIT\n",
  "bytes": 8668,
  "sha": "26d2d2176f637d9760bead3b51d17272f92231aa93b5264c997ceb74e2993250",
  "repo_slug": "callstackincubator/agent-react-devtools",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_callstackincubator_agent_react_devtools__a9cc464d/readme"
}