{"id":50826538,"url":"https://github.com/callstackincubator/agent-react-devtools","last_synced_at":"2026-06-13T19:35:24.479Z","repository":{"id":337699408,"uuid":"1153440204","full_name":"callstackincubator/agent-react-devtools","owner":"callstackincubator","description":"Gives AI agents access to React DevTools ⚛️🤖","archived":false,"fork":false,"pushed_at":"2026-04-04T01:42:06.000Z","size":288,"stargazers_count":226,"open_issues_count":6,"forks_count":9,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-13T19:35:23.156Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/callstackincubator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-09T09:55:45.000Z","updated_at":"2026-06-10T12:04:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/callstackincubator/agent-react-devtools","commit_stats":null,"previous_names":["piotrski/agent-react-devtools","callstackincubator/agent-react-devtools"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/callstackincubator/agent-react-devtools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstackincubator%2Fagent-react-devtools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstackincubator%2Fagent-react-devtools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstackincubator%2Fagent-react-devtools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstackincubator%2Fagent-react-devtools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/callstackincubator","download_url":"https://codeload.github.com/callstackincubator/agent-react-devtools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/callstackincubator%2Fagent-react-devtools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34298247,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-13T19:35:23.862Z","updated_at":"2026-06-13T19:35:24.475Z","avatar_url":"https://github.com/callstackincubator.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 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 (`\u003cdiv\u003e`, `\u003cspan\u003e`, etc.) are filtered by default to keep output compact. Use `--all` to include them. Host components with keys or custom element names (e.g. `\u003cmy-widget\u003e`) 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 \u003c@c1 | id\u003e      # Props, state, hooks\nagent-react-devtools find \u003cname\u003e [--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 \u003c@c1 | id\u003e      # 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 \u003cN | #N\u003e [--limit N]  # Single commit detail\nagent-react-devtools profile export \u003cfile\u003e               # Export as React DevTools Profiler JSON\nagent-react-devtools profile diff \u003cbefore.json\u003e \u003cafter.json\u003e [--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 \u003cName\u003e` — 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcallstackincubator%2Fagent-react-devtools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcallstackincubator%2Fagent-react-devtools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcallstackincubator%2Fagent-react-devtools/lists"}