agent-react-devtools 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # agent-react-devtools
 
+## 0.2.1
+
+### Patch Changes
+
+- 0c2de5b: Add Claude Code skill and plugin marketplace metadata
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -198,9 +198,28 @@ For Expo, the connection works automatically with the Expo dev client.
 
 To use a custom port, set the `REACT_DEVTOOLS_PORT` environment variable.
 
-## Using with AI Agents
+## Using with AI Coding Assistants
 
-Add something like this to your project's `CLAUDE.md` (or equivalent agent instructions):
+Add the skill to your AI coding assistant for richer context:
+
+```sh
+npx skills add piotrski/agent-react-devtools
+```
+
+This works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf.
+
+### Claude Code plugin
+
+You can also install via the Claude Code plugin marketplace:
+
+```
+/plugin marketplace add piotrski/agent-react-devtools
+/plugin install agent-react-devtools@piotrski
+```
+
+### Manual setup
+
+Alternatively, add something like this to your project's `CLAUDE.md` (or equivalent agent instructions):
 
 ```markdown
 ## React Debugging

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-react-devtools",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "CLI tool for AI agents to inspect React component trees and profile performance",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "CHANGELOG.md"
   ],

package/skills/react-devtools/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: react-devtools
+description: React DevTools CLI for AI agents. Use when the user asks you to debug a React or React Native app at runtime, inspect component props/state/hooks, diagnose render performance, profile re-renders, find slow components, or understand why something re-renders. Triggers include "why does this re-render", "inspect the component", "what props does X have", "profile the app", "find slow components", "debug the UI", "check component state", "the app feels slow", or any React runtime debugging task.
+allowed-tools: Bash(agent-react-devtools:*)
+---
+
+# agent-react-devtools
+
+CLI that connects to a running React or React Native app via the React DevTools protocol and exposes the component tree, props, state, hooks, and profiling data in a token-efficient format.
+
+## Core Workflow
+
+1. **Ensure connection** — check `agent-react-devtools status`. If the daemon is not running, start it with `agent-react-devtools start`.
+2. **Inspect** — get the component tree, search for components, inspect props/state/hooks.
+3. **Profile** — start profiling, trigger the interaction (or ask the user to), stop profiling, analyze results.
+4. **Act** — use the data to fix the bug, optimize performance, or explain what's happening.
+
+## Essential Commands
+
+### Daemon
+
+```bash
+agent-react-devtools start              # Start daemon (auto-starts on first command)
+agent-react-devtools stop               # Stop daemon
+agent-react-devtools status             # Check connection: port, connected apps, component count
+```
+
+### Component Inspection
+
+```bash
+agent-react-devtools get tree           # Full component hierarchy (labels: @c1, @c2, ...)
+agent-react-devtools get tree --depth 3 # Limit depth
+agent-react-devtools get component @c5  # Props, state, hooks for a specific component
+agent-react-devtools find Button        # Search by display name (fuzzy)
+agent-react-devtools find Button --exact # Exact match
+agent-react-devtools count              # Count by type: fn, cls, host, memo, ...
+```
+
+### Performance Profiling
+
+```bash
+agent-react-devtools profile start              # Start recording
+agent-react-devtools profile stop               # Stop and collect data
+agent-react-devtools profile slow               # Slowest components by avg render time
+agent-react-devtools profile slow --limit 10    # Top 10
+agent-react-devtools profile rerenders          # Most re-rendered components
+agent-react-devtools profile report @c5         # Detailed report for one component
+agent-react-devtools profile timeline           # Chronological commit list
+agent-react-devtools profile commit 3           # Detail for commit #3
+```
+
+## Understanding the Output
+
+### Component Labels
+
+Every component gets a stable label like `@c1`, `@c2`. Use these to reference components in follow-up commands:
+
+```
+@c1 [fn] "App"
+├─ @c2 [fn] "Header"
+├─ @c3 [fn] "TodoList"
+│  ├─ @c4 [fn] "TodoItem" key="1"
+│  └─ @c5 [fn] "TodoItem" key="2"
+└─ @c6 [host] "div"
+```
+
+Type abbreviations: `fn` = function, `cls` = class, `host` = DOM element, `memo` = React.memo, `fRef` = forwardRef, `susp` = Suspense, `ctx` = context.
+
+### Inspected Component
+
+```
+@c3 [fn] "TodoList"
+props:
+  items: [{"id":1,"text":"Buy milk"},{"id":2,"text":"Walk dog"}]
+  onDelete: ƒ
+state:
+  filter: "all"
+hooks:
+  useState: "all"
+  useMemo: [...]
+  useCallback: ƒ
+```
+
+`ƒ` = function value. Values over 60 chars are truncated.
+
+### Profiling Output
+
+```
+Slowest (by avg render time):
+  ExpensiveList        avg:12.3ms  max:18.1ms  renders:47  cause:props-changed
+  TodoItem             avg:2.1ms   max:5.0ms   renders:94  cause:parent-rendered
+```
+
+Render causes: `props-changed`, `state-changed`, `hooks-changed`, `parent-rendered`, `force-update`, `first-mount`.
+
+## Common Patterns
+
+### Diagnose slow interactions
+
+```bash
+agent-react-devtools profile start
+# User interacts with the app (or use agent-browser to drive the UI)
+agent-react-devtools profile stop
+agent-react-devtools profile slow --limit 5
+agent-react-devtools profile rerenders --limit 5
+```
+
+Then inspect the worst offenders with `get component @cN` and `profile report @cN`.
+
+### Find a component and check its state
+
+```bash
+agent-react-devtools find SearchBar
+agent-react-devtools get component @c12
+```
+
+### Verify a fix worked
+
+```bash
+agent-react-devtools profile start
+# Repeat the interaction
+agent-react-devtools profile stop
+agent-react-devtools profile slow --limit 5
+# Compare render counts and durations to the previous run
+```
+
+## Important Rules
+
+- **Labels reset** when the app reloads or components unmount/remount. Always re-check with `get tree` or `find` after a page reload.
+- **`status` first** — if status shows 0 connected apps, the React app is not connected. The user may need to run `npx agent-react-devtools init` in their project first.
+- **Profile while interacting** — profiling only captures renders that happen between `profile start` and `profile stop`. Make sure the relevant interaction happens during that window.
+- **Use `--depth`** on large trees — a deep tree can produce a lot of output. Start with `--depth 3` or `--depth 4` and go deeper only on the subtree you care about.
+
+## References
+
+| File | When to read |
+|------|-------------|
+| [commands.md](references/commands.md) | Full command reference with all flags and edge cases |
+| [profiling-guide.md](references/profiling-guide.md) | Step-by-step profiling workflows and interpreting results |
+| [setup.md](references/setup.md) | How to connect different frameworks (Vite, Next.js, Expo, CRA) |

package/skills/react-devtools/references/commands.md

@@ -0,0 +1,82 @@
+# Command Reference
+
+## Daemon Management
+
+### `agent-react-devtools start [--port N]`
+Start the background daemon. Default port: 8097. The daemon listens for WebSocket connections from React apps and IPC connections from the CLI. Auto-starts when you run any other command, so you rarely need this explicitly.
+
+### `agent-react-devtools stop`
+Stop the daemon process. All connection state is lost.
+
+### `agent-react-devtools status`
+Show daemon status: port, connected apps, component count, profiling state, uptime.
+
+Output:
+```
+Daemon: running (port 8097)
+Apps: 1 connected, 42 components
+Uptime: 120s
+```
+
+If profiling is active, shows `Profiling: active`.
+
+## Component Inspection
+
+### `agent-react-devtools get tree [--depth N]`
+Print the component hierarchy as an indented tree. Each node shows:
+- Label (`@c1`, `@c2`, ...) — stable within a session, resets on app reload
+- Type tag (`fn`, `cls`, `host`, `memo`, `fRef`, `susp`, `ctx`)
+- Display name
+- Key (if present)
+
+Use `--depth N` to limit tree depth. Recommended for large apps.
+
+### `agent-react-devtools get component <@cN | id>`
+Inspect a single component. Shows:
+- **props** — all prop values (functions shown as `ƒ`, long values truncated at 60 chars)
+- **state** — state values (class components and useState)
+- **hooks** — all hooks with current values and sub-hooks
+
+Accepts a label (`@c5`) or numeric React fiber ID.
+
+### `agent-react-devtools find <name> [--exact]`
+Search components by display name. Default is case-insensitive substring match. Use `--exact` for exact match.
+
+Returns a flat list of matching components with labels, types, and keys.
+
+### `agent-react-devtools count`
+Count components by type. Output: `42 components (fn:25 host:12 memo:3 cls:2)`.
+
+## Profiling
+
+### `agent-react-devtools profile start [name]`
+Start a profiling session. Optional name for identification. Only one session can be active at a time.
+
+### `agent-react-devtools profile stop`
+Stop profiling and collect data from React. Shows a summary with duration, commit count, and top rendered components.
+
+### `agent-react-devtools profile slow [--limit N]`
+Rank components by average render duration (slowest first). Default limit: 10.
+
+Output columns: component name, avg duration, max duration, render count, primary cause.
+
+### `agent-react-devtools profile rerenders [--limit N]`
+Rank components by render count (most re-renders first). Default limit: 10.
+
+Output columns: component name, render count, primary cause.
+
+### `agent-react-devtools profile report <@cN | id>`
+Detailed render report for a single component: render count, avg/max/total duration, all render causes.
+
+### `agent-react-devtools profile timeline [--limit N]`
+Chronological list of React commits during the profiling session. Each entry: index, duration, component count.
+
+### `agent-react-devtools profile commit <N | #N> [--limit N]`
+Detail for a specific commit by index. Shows per-component self/total duration and render causes.
+
+## Setup
+
+### `agent-react-devtools init [--dry-run]`
+Auto-detect the framework in the current directory and configure the devtools connection. Supports Vite, Next.js, CRA, and Expo/React Native.
+
+Use `--dry-run` to preview changes without writing files.

package/skills/react-devtools/references/profiling-guide.md

@@ -0,0 +1,110 @@
+# Profiling Guide
+
+## Quick Start
+
+```bash
+agent-react-devtools profile start
+# Trigger the slow interaction (type, click, navigate)
+agent-react-devtools profile stop
+agent-react-devtools profile slow --limit 5
+```
+
+## Step-by-Step Workflow
+
+### 1. Establish a Baseline
+
+Before profiling, check the current state:
+
+```bash
+agent-react-devtools status          # Confirm app is connected
+agent-react-devtools count           # How many components are mounted
+agent-react-devtools get tree --depth 3  # Understand the structure
+```
+
+### 2. Profile the Interaction
+
+Start profiling, then trigger the specific interaction the user reports as slow:
+
+```bash
+agent-react-devtools profile start "typing in search"
+```
+
+The user should perform the interaction now. If using agent-browser, you can drive the interaction programmatically.
+
+```bash
+agent-react-devtools profile stop
+```
+
+### 3. Identify Bottlenecks
+
+**Slowest components** — which components take the most time per render:
+```bash
+agent-react-devtools profile slow --limit 5
+```
+
+**Most re-rendered** — which components render too often:
+```bash
+agent-react-devtools profile rerenders --limit 5
+```
+
+These two views complement each other:
+- A component that renders 100 times at 0.1ms each = 10ms total (re-render problem)
+- A component that renders 2 times at 50ms each = 100ms total (slow render problem)
+
+### 4. Drill Into Specific Components
+
+Once you identify a suspect, get its full render report:
+
+```bash
+agent-react-devtools profile report @c12
+```
+
+This shows all render causes. Common patterns:
+
+| Cause | Meaning | Typical Fix |
+|-------|---------|-------------|
+| `parent-rendered` | Parent re-rendered, child has no bailout | Wrap child in `React.memo()` |
+| `props-changed` | Received new prop references | Stabilize with `useMemo`/`useCallback` in parent |
+| `state-changed` | Component's own state changed | Check if state update is necessary |
+| `hooks-changed` | A hook dependency changed | Review hook dependencies |
+| `first-mount` | Initial render | Normal — not a problem |
+
+### 5. Inspect the Component
+
+Read the component's current props and hooks to understand what's changing:
+
+```bash
+agent-react-devtools get component @c12
+```
+
+Look for:
+- Function props (`ƒ`) — likely unstable references if not wrapped in `useCallback`
+- Object/array props — likely new references if not wrapped in `useMemo`
+- State that updates too frequently
+
+### 6. Fix and Verify
+
+After applying the fix, re-profile with the same interaction:
+
+```bash
+agent-react-devtools profile start "after fix"
+# Same interaction
+agent-react-devtools profile stop
+agent-react-devtools profile slow --limit 5
+```
+
+Compare render counts and durations to confirm improvement.
+
+## Common Performance Issues
+
+### Cascading re-renders from context or lifted state
+A parent component re-renders (e.g., from a timer or context change) and all children re-render because none use `React.memo`. Look for high re-render counts with `parent-rendered` cause.
+
+### Unstable prop references
+Parent passes `onClick={() => ...}` or `style={{...}}` inline — creates new references every render, defeating `memo()`. The child shows `props-changed` as the cause even though the values are semantically identical.
+
+### Expensive computations without memoization
+A component does heavy work (filtering, sorting, formatting) on every render. Shows up as high avg render time. Fix with `useMemo`.
+
+### State updates in effects causing render loops
+An effect updates state on every render, causing unnecessary commit cycles. Look for unusually high commit counts in `profile timeline`.

package/skills/react-devtools/references/setup.md

@@ -0,0 +1,100 @@
+# Setup Guide
+
+agent-react-devtools works with any React or React Native app. The `init` command auto-detects your framework and configures everything.
+
+## Auto Setup (Recommended)
+
+```bash
+cd your-react-app
+npx agent-react-devtools init
+```
+
+This detects the framework and applies the minimal configuration needed.
+
+Use `--dry-run` to preview changes without modifying files:
+```bash
+npx agent-react-devtools init --dry-run
+```
+
+## Framework-Specific Details
+
+### Vite
+
+`init` adds the Vite plugin to your config:
+
+```ts
+// vite.config.ts
+import { reactDevtools } from "agent-react-devtools/vite";
+
+export default defineConfig({
+  plugins: [reactDevtools(), react()],
+});
+```
+
+The plugin only runs in dev mode (`vite dev`). It injects the connect script before your app code loads. Zero app code changes needed.
+
+### Next.js (App Router)
+
+`init` creates a client component that imports the connect script and adds it to your root layout:
+
+```tsx
+// app/devtools.tsx
+'use client';
+import 'agent-react-devtools/connect';
+export default function DevTools() { return null; }
+```
+
+Then imports it in `app/layout.tsx`.
+
+### Create React App
+
+`init` prepends the import to `src/index.tsx`:
+
+```ts
+import 'agent-react-devtools/connect';
+```
+
+### React Native / Expo
+
+React Native apps auto-connect to the devtools WebSocket on port 8097 — no code changes needed.
+
+```bash
+agent-react-devtools start
+npx react-native start
+# or: npx expo start
+```
+
+For physical devices, reverse the port:
+```bash
+adb reverse tcp:8097 tcp:8097
+```
+
+## Manual Setup
+
+If `init` doesn't cover your setup, add this as the first import in your entry point:
+
+```ts
+import 'agent-react-devtools/connect';
+```
+
+The connect script is:
+- **SSR-safe** — no-ops on the server
+- **Production-safe** — tree-shaken in production builds
+- Connects via WebSocket with a 2-second timeout
+
+## Verifying the Connection
+
+```bash
+agent-react-devtools status
+```
+
+Expected output when connected:
+```
+Daemon: running (port 8097)
+Apps: 1 connected, 42 components
+```
+
+If `Apps: 0 connected`:
+1. Check the app is running in dev mode
+2. Check the console for WebSocket connection errors
+3. Ensure no other DevTools instance is using port 8097