Skip to content

Commit 10ac53c

Browse files
piotrskipiotrski
authored
docs: add README, LICENSE, and npm package config (#6)
1 parent 088e10a commit 10ac53c

File tree

5 files changed

+203
-11
lines changed

5 files changed

+203
-11
lines changed

‎.changeset/add-readme-and-license.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"agent-react-devtools": patch
3+
---
4+
5+
Add comprehensive README with usage examples and MIT LICENSE file

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ dist/
66
# Bun
77
bun.lock
88

9+
# Generated at publish time
10+
packages/agent-react-devtools/README.md
11+
912
# Examples
1013
examples/*/node_modules/
1114
examples/*/dist/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025-present Piotr Tomczewski
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 167 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,178 @@
11
# agent-react-devtools
22

3-
CLI tool for AI agents to inspect React component trees and profile rendering performance. Connects to running React apps via the React DevTools protocol.
3+
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).
44

5-
## Development
5+
The project is in early development and considered experimental. Pull requests are welcome!
6+
7+
## Features
8+
9+
- Walk the full component tree with props, state, and hooks
10+
- Search for components by display name
11+
- Profile renders: find slow components, excessive re-renders, and commit timelines
12+
- Persistent background daemon that survives across CLI calls
13+
- Token-efficient output built for LLM consumption
14+
15+
## Install
16+
17+
```sh
18+
npm install -g agent-react-devtools
19+
```
20+
21+
Or run it directly:
22+
23+
```sh
24+
npx agent-react-devtools start
25+
```
26+
27+
## Quick Start
28+
29+
```sh
30+
agent-react-devtools start
31+
agent-react-devtools status
32+
```
33+
34+
```
35+
Daemon: running (port 8097)
36+
Apps: 1 connected, 24 components
37+
Uptime: 12s
38+
```
39+
40+
Browse the component tree:
41+
42+
```sh
43+
agent-react-devtools get tree --depth 3
44+
```
45+
46+
```
47+
@c1 [fn] "App"
48+
├─ @c2 [fn] "Header"
49+
│ ├─ @c3 [fn] "Nav"
50+
│ └─ @c4 [fn] "SearchBar"
51+
├─ @c5 [fn] "TodoList"
52+
│ ├─ @c6 [fn] "TodoItem" key="1"
53+
│ ├─ @c7 [fn] "TodoItem" key="2"
54+
│ └─ @c8 [fn] "TodoItem" key="3"
55+
└─ @c9 [fn] "Footer"
56+
```
57+
58+
Inspect a component's props, state, and hooks:
59+
60+
```sh
61+
agent-react-devtools get component @c6
62+
```
63+
64+
```
65+
@c6 [fn] "TodoItem" key="1"
66+
props:
67+
id: 1
68+
text: "Buy groceries"
69+
done: false
70+
onToggle: ƒ
71+
hooks:
72+
State: false
73+
Callback: ƒ
74+
```
75+
76+
Find components by name:
677

778
```sh
8-
# Install dependencies
9-
bun install
79+
agent-react-devtools find TodoItem
80+
```
1081

11-
# Build
12-
bun run build
82+
```
83+
@c6 [fn] "TodoItem" key="1"
84+
@c7 [fn] "TodoItem" key="2"
85+
@c8 [fn] "TodoItem" key="3"
86+
```
1387

14-
# Run tests
15-
bun run test
88+
Profile rendering performance:
1689

17-
# Type check
18-
bun run typecheck
90+
```sh
91+
agent-react-devtools profile start
92+
# ... interact with the app ...
93+
agent-react-devtools profile stop
94+
agent-react-devtools profile slow
95+
```
96+
97+
```
98+
Slowest (by avg render time):
99+
TodoList avg:4.2ms max:8.1ms renders:6 cause:props
100+
SearchBar avg:2.1ms max:3.4ms renders:12 cause:hooks
101+
Header avg:0.8ms max:1.2ms renders:3 cause:parent
102+
```
103+
104+
## Commands
105+
106+
### Daemon
107+
108+
```sh
109+
agent-react-devtools start [--port 8097] # Start daemon
110+
agent-react-devtools stop # Stop daemon
111+
agent-react-devtools status # Connection status
112+
```
113+
114+
### Components
115+
116+
```sh
117+
agent-react-devtools get tree [--depth N] # Component hierarchy
118+
agent-react-devtools get component <@c1 | id> # Props, state, hooks
119+
agent-react-devtools find <name> [--exact] # Search by display name
120+
agent-react-devtools count # Component count by type
121+
```
122+
123+
Components are labeled `@c1`, `@c2`, etc. You can use these labels or numeric IDs interchangeably.
124+
125+
### Profiling
126+
127+
```sh
128+
agent-react-devtools profile start [name] # Begin a profiling session
129+
agent-react-devtools profile stop # Stop and collect data
130+
agent-react-devtools profile report <@c1 | id> # Render report for a component
131+
agent-react-devtools profile slow [--limit N] # Slowest components by avg duration
132+
agent-react-devtools profile rerenders [--limit N] # Most re-rendered components
133+
agent-react-devtools profile timeline [--limit N] # Commit timeline
134+
agent-react-devtools profile commit <N | #N> [--limit N] # Single commit detail
135+
```
136+
137+
## Connecting Your App
138+
139+
Install `react-devtools-core` in your app and connect before React renders (e.g. in `src/main.tsx`):
140+
141+
```ts
142+
import { initialize, connectToDevTools } from 'react-devtools-core';
143+
import { createRoot } from 'react-dom/client';
144+
import App from './App';
145+
146+
initialize();
147+
connectToDevTools({ port: 8097 });
148+
149+
createRoot(document.getElementById('root')!).render(<App />);
150+
```
151+
152+
## Using with AI Agents
153+
154+
Add something like this to your project's `CLAUDE.md` (or equivalent agent instructions):
155+
156+
```markdown
157+
## React Debugging
158+
159+
This project uses agent-react-devtools to inspect the running React app.
160+
161+
- `agent-react-devtools start` — start the daemon
162+
- `agent-react-devtools status` — check if the app is connected
163+
- `agent-react-devtools get tree` — see the component hierarchy
164+
- `agent-react-devtools get component @c1` — inspect a specific component
165+
- `agent-react-devtools find <Name>` — search for components
166+
- `agent-react-devtools profile start` / `profile stop` / `profile slow` — diagnose render performance
167+
```
168+
169+
## Development
170+
171+
```sh
172+
bun install # Install dependencies
173+
bun run build # Build
174+
bun run test # Run tests
175+
bun run typecheck # Type check
19176
```
20177

21178
## License

‎packages/agent-react-devtools/package.json‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,19 @@
66
"bin": {
77
"agent-react-devtools": "./dist/cli.js"
88
},
9+
"files": [
10+
"dist",
11+
"README.md",
12+
"CHANGELOG.md"
13+
],
914
"scripts": {
1015
"build": "tsup",
1116
"dev": "tsup --watch",
1217
"test": "vitest run",
1318
"test:watch": "vitest",
1419
"typecheck": "tsc --noEmit",
15-
"lint": "tsc --noEmit"
20+
"lint": "tsc --noEmit",
21+
"prepublishOnly": "cp ../../README.md ."
1622
},
1723
"repository": {
1824
"type": "git",

0 commit comments

Comments
 (0)