agent-react-devtools 0.0.0 → 0.1.1-canary-20260210005551

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# agent-react-devtools
+
+## 0.1.1-canary-20260210005551
+
+### Patch Changes
+
+- 10ac53c: Add comprehensive README with usage examples and MIT LICENSE file
+
+## 0.1.0
+
+### Minor Changes
+
+- d1e02f9: **Daemon, DevTools bridge, and component tree**
+
+  **Daemon** — Persistent background process with IPC server (Unix socket) that manages connections and dispatches commands.
+
+  **DevTools Bridge** — WebSocket server implementing the React DevTools "Wall" protocol. Connects to running React apps via `react-devtools-core`.
+
+  **Component Tree** — Parse and inspect the full React component hierarchy:
+
+  - View component tree with types, keys, and parent/child relationships
+  - Inspect props, state, and hooks of any component
+  - Search components by display name (fuzzy or exact match)
+  - Count components by type
+
+  **CLI** — Command-line interface with commands: `start`, `stop`, `status`, `tree`, `find`, `count`, `get component`.
+
+  **Formatting** — Token-efficient output designed for LLM consumption.
+
+- 626a21a: **Profiler**
+
+  Start and stop profiling sessions to capture render performance data from connected React apps.
+
+  - **Render reports** — Per-component render duration and count
+  - **Slowest components** — Ranked by self render time
+  - **Most re-rendered** — Ranked by render count
+  - **Commit timeline** — Chronological view of React commits with durations
+  - **Commit details** — Per-component breakdown for a specific commit, sorted by self time
+
+  CLI commands: `profile start`, `profile stop`, `profile report`, `profile slow`, `profile rerenders`, `profile timeline`, `profile commit`.

package/README.md

@@ -0,0 +1,180 @@
+# 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](https://github.com/vercel-labs/agent-browser) and Callstack's [agent-device](https://github.com/callstackincubator/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
+
+```sh
+npm install -g agent-react-devtools
+```
+
+Or run it directly:
+
+```sh
+npx agent-react-devtools start
+```
+
+## Quick Start
+
+```sh
+agent-react-devtools start
+agent-react-devtools status
+```
+
+```
+Daemon: running (port 8097)
+Apps: 1 connected, 24 components
+Uptime: 12s
+```
+
+Browse the component tree:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+agent-react-devtools find TodoItem
+```
+
+```
+@c6 [fn] "TodoItem" key="1"
+@c7 [fn] "TodoItem" key="2"
+@c8 [fn] "TodoItem" key="3"
+```
+
+Profile rendering performance:
+
+```sh
+agent-react-devtools profile start
+# ... interact with the app ...
+agent-react-devtools profile stop
+agent-react-devtools profile slow
+```
+
+```
+Slowest (by avg render time):
+  TodoList             avg:4.2ms  max:8.1ms  renders:6  cause:props
+  SearchBar            avg:2.1ms  max:3.4ms  renders:12 cause:hooks
+  Header               avg:0.8ms  max:1.2ms  renders:3  cause:parent
+```
+
+## Commands
+
+### Daemon
+
+```sh
+agent-react-devtools start [--port 8097]   # Start daemon
+agent-react-devtools stop                   # Stop daemon
+agent-react-devtools status                 # Connection status
+```
+
+### Components
+
+```sh
+agent-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 type
+```
+
+Components are labeled `@c1`, `@c2`, etc. You can use these labels or numeric IDs interchangeably.
+
+### Profiling
+
+```sh
+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
+```
+
+## Connecting Your App
+
+Install `react-devtools-core` in your app and connect before React renders (e.g. in `src/main.tsx`):
+
+```ts
+import { initialize, connectToDevTools } from 'react-devtools-core';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+
+initialize();
+connectToDevTools({ port: 8097 });
+
+createRoot(document.getElementById('root')!).render(<App />);
+```
+
+## Using with AI Agents
+
+Add something like this to your project's `CLAUDE.md` (or equivalent agent instructions):
+
+```markdown
+## 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 performance
+```
+
+## Development
+
+```sh
+bun install        # Install dependencies
+bun run build      # Build
+bun run test       # Run tests
+bun run typecheck  # Type check
+```
+
+## License
+
+MIT