feat: add react devtools passthrough (#435)

* feat: add react devtools passthrough

* docs: clarify react devtools passthrough

* fix: preserve react devtools global flags

* docs: add react devtools validation guidance

* docs: simplify react devtools validation notes

Author: thymikee

README.md

@@ -37,7 +37,17 @@ If you know Vercel's [agent-browser](https://github.com/vercel-labs/agent-browse
 
 Use `agent-device` for on-device UI automation, screenshots/recordings, app logs, network inspection, and performance snapshots.
 
-When the task needs the React component tree, props, state, hooks, or render profiling, pair it with the complementary [`agent-react-devtools`](https://github.com/callstackincubator/agent-react-devtools) project. The two tools solve different layers of the same debugging workflow.
+When the task needs the React Native component tree, props, state, hooks, or render profiling, use the bundled passthrough:
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools get tree --depth 3
+agent-device react-devtools profile start
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+```
+
+`react-devtools` dynamically runs pinned `agent-react-devtools@0.4.0` commands 1:1, so `agent-device` covers both the device/app runtime layer and React component internals without making React DevTools part of the daemon.
 
 ## Command Flow
 
@@ -77,6 +87,7 @@ For people:
 For agents:
 
 - [agent-device skill](skills/agent-device/SKILL.md)
+- [react-devtools skill](skills/react-devtools/SKILL.md)
 - [dogfood skill](skills/dogfood/SKILL.md)
 - [agent-device skill on ClawHub](https://clawhub.ai/okwasniewski/agent-device)
 

skills/agent-device/SKILL.md

@@ -71,4 +71,4 @@ Use this skill as a router with mandatory defaults. Read this file first. For no
 - Need desktop surfaces, menu bar behavior, or macOS-specific interaction rules: [references/macos-desktop.md](references/macos-desktop.md)
 - Need remote HTTP transport, `connect --remote-config`, or tenant leases on a remote macOS host: [references/remote-tenancy.md](references/remote-tenancy.md)
   This includes remote React Native runs where `agent-device` now prepares Metro locally and manages the local Metro companion tunnel automatically.
-- Need the React component tree, props, state, hooks, or render profiling: pair `agent-device` with the complementary [`agent-react-devtools`](https://github.com/callstackincubator/agent-react-devtools) project when available.
+- Need the React Native component tree, props, state, hooks, or render profiling: use `agent-device react-devtools ...` and the [react-devtools skill](../react-devtools/SKILL.md).

skills/agent-device/references/debugging.md

@@ -4,7 +4,7 @@
 
 Open this file when the task turns into failure triage, logs, network inspection, permission prompts, setup trouble, or unstable session behavior.
 
-If the debugging task needs the React component tree, props, state, hooks, or render profiling, pair `agent-device` with the complementary [`agent-react-devtools`](https://github.com/callstackincubator/agent-react-devtools) project instead of trying to infer those internals from the accessibility tree or app logs alone.
+If the debugging task needs the React Native component tree, props, state, hooks, or render profiling, use `agent-device react-devtools ...` and the `skills/react-devtools` workflow instead of trying to infer those internals from the accessibility tree or app logs alone.
 
 ## Main commands to reach for first
 

skills/agent-device/references/exploration.md

@@ -20,7 +20,7 @@ Open this file when the app or screen is already running and you need to discove
 - User asks what is visible on screen: `snapshot`
 - User asks for exact text from a known target: `get text`
 - User asks you to tap, type, or choose an element: `snapshot -i`, then act
-- User asks for the React component tree, props/state/hooks, or render profiling: pair `agent-device` with the complementary [`agent-react-devtools`](https://github.com/callstackincubator/agent-react-devtools) project
+- User asks for the React Native component tree, props/state/hooks, or render profiling: use `agent-device react-devtools ...` and the `skills/react-devtools` workflow
 - React Native dev or debug build shows warning/error UI: capture enough evidence to identify it, dismiss it if it is not the requested behavior, then continue the flow and report it in the summary
 - The on-screen keyboard is blocking the next step: `keyboard dismiss`; on iOS do this only while an app session is active, and use `keyboard status|get` only on Android
 - UI does not expose the answer: say so plainly; do not browse or force the app into a new state unless asked

skills/dogfood/SKILL.md

@@ -166,7 +166,7 @@ agent-device --session {SESSION} close
 - Re-snapshot after any mutation (navigation, modal, list update, form submit).
 - Use `fill` for clear-then-type semantics; use `type` for incremental typing behavior checks.
 - Keep logs optional and targeted: enable/read app logs only when useful for diagnosis.
-- If the issue appears rooted in React internals rather than device/app runtime behavior, pair `agent-device` with the complementary [`agent-react-devtools`](https://github.com/callstackincubator/agent-react-devtools) project for component-tree or render-profiling inspection.
+- If the issue appears rooted in React Native internals rather than device/app runtime behavior, use `agent-device react-devtools ...` and the `skills/react-devtools` workflow for component-tree or render-profiling inspection.
 - Never read source code of the app under test; findings must come from observed runtime behavior.
 - Write each issue immediately to avoid losing evidence.
 - Never delete screenshots/videos/report artifacts during a session.

skills/react-devtools/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: react-devtools
+description: Inspect and profile React Native component trees from agent-device. Use when debugging React Native props, state, hooks, render causes, slow components, excessive re-renders, or questions like why a component re-rendered.
+---
+
+# react-devtools
+
+Use this skill when the task needs React Native internals that are not visible in the accessibility tree: component hierarchy, props, state, hooks, render causes, or profiling data.
+
+Run commands through `agent-device react-devtools`. The command dynamically runs pinned `agent-react-devtools@0.4.0` and passes arguments through 1:1.
+
+The first run may download the pinned package from npm. `agent-device` global flags work before or after `react-devtools`; use `--` before downstream flags only when they intentionally share an `agent-device` global flag name.
+
+## Default flow
+
+1. Use `agent-device` to open the React Native app and verify the visible state when needed.
+2. Check `agent-device react-devtools status`.
+3. If no app is connected, start or wait for the devtools daemon, then reload or relaunch the app.
+4. Inspect with `get tree`, `find`, and `get component`.
+5. Profile only around the interaction being investigated.
+6. Verify the fix with the same command sequence and interaction.
+
+For cross-platform validation with explicit `--device`, `--udid`, or `--serial` selectors, prefer an isolated `--state-dir` over separate named sessions. Named sessions enable bound-session locks during setup. Restart `agent-device react-devtools` between iOS and Android runs so `status`, `get tree`, and profiling clearly refer to the currently launched app.
+
+## Main commands
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools wait --connected
+agent-device react-devtools get tree --depth 3
+agent-device react-devtools find <ComponentName>
+agent-device react-devtools get component @c5
+agent-device react-devtools profile start
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+## Decision rules
+
+- Need current UI text, refs, screenshots, logs, network, or device metrics: use the `agent-device` skill.
+- Need props, state, hooks, component ownership, render causes, or React profiler data: use this skill.
+- Start component-tree reads with `get tree --depth 3` or `find <name>` to keep output bounded.
+- Labels like `@c5` reset when the app reloads or components remount. After reload, run `wait --connected` and inspect again.
+- Profiling only captures renders between `profile start` and `profile stop`.
+- On Android, set `adb reverse tcp:8097 tcp:8097` for React DevTools. If Metro is local, also set `adb reverse tcp:8081 tcp:8081`.
+
+## References
+
+| File                                    | When to read                                  |
+| --------------------------------------- | --------------------------------------------- |
+| [commands.md](references/commands.md)   | Command reference and common inspection flows |
+| [profiling.md](references/profiling.md) | Render profiling workflow and interpretation  |

skills/react-devtools/references/commands.md

@@ -0,0 +1,91 @@
+# React DevTools Commands
+
+All commands are run through `agent-device react-devtools`.
+
+## Connection
+
+```bash
+agent-device react-devtools start
+agent-device react-devtools stop
+agent-device react-devtools status
+agent-device react-devtools wait --connected --timeout 30
+agent-device react-devtools wait --component <ComponentName> --timeout 30
+```
+
+- `status` shows the daemon port, connected apps, component count, profiling state, uptime, and last connection event.
+- Most commands auto-start the daemon, but `start` is useful before launching or reloading the app.
+- React Native development builds connect to the daemon on port 8097. For Android emulators or physical devices, use `adb reverse tcp:8097 tcp:8097` if the app cannot reach the host. If the app also uses local Metro, set `adb reverse tcp:8081 tcp:8081`.
+
+## Validation Notes
+
+- When validating the same app across iOS and Android with explicit `--device`, `--udid`, or `--serial` selectors, prefer an isolated `--state-dir` over separate named sessions. A named `--session` enables bound-session lock behavior, so setup commands with explicit target selectors can be rejected.
+- Restart the React DevTools daemon between platforms so `status`, `get tree`, and profiling output belong to the currently launched app.
+- Verify the app is visibly loaded with `snapshot` before collecting React internals. Use `react-devtools` for component state and profiling, not for proving the device/app surface is open.
+
+## Component Inspection
+
+```bash
+agent-device react-devtools get tree --depth 3
+agent-device react-devtools get component @c5
+agent-device react-devtools find Button
+agent-device react-devtools find Button --exact
+agent-device react-devtools count
+agent-device react-devtools errors
+```
+
+- `get tree` prints a component hierarchy with labels like `@c1`, `@c2`.
+- Use `--depth` on large apps. Start at `--depth 3` or `--depth 4`.
+- `get component` accepts a label or numeric React fiber id and shows props, state, and hooks.
+- `find` searches by display name. Use `--exact` when fuzzy results are noisy.
+- `errors` lists components with React-tracked warnings or errors.
+
+## Profiling
+
+```bash
+agent-device react-devtools profile start "interaction name"
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+agent-device react-devtools profile report @c5
+agent-device react-devtools profile timeline --limit 20
+agent-device react-devtools profile commit 3
+agent-device react-devtools profile export profile.json
+agent-device react-devtools profile diff before.json after.json --limit 10
+```
+
+- `profile slow` ranks components by average render duration.
+- `profile rerenders` ranks components by render count.
+- `profile report @cN` shows render causes and changed props/state/hooks for one component.
+- `profile timeline` lists commits. Use `--limit` and `--offset` for long sessions.
+- `profile export` writes React DevTools Profiler JSON that can be diffed later.
+
+## Common Flows
+
+Inspect a component:
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools get tree --depth 3
+agent-device react-devtools find SearchScreen
+agent-device react-devtools get component @c12
+```
+
+Profile a slow interaction:
+
+```bash
+agent-device react-devtools profile start "slow search"
+# Trigger the interaction with agent-device or ask the user to perform it.
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+Verify a render fix:
+
+```bash
+agent-device react-devtools profile start "after fix"
+# Repeat the same interaction.
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```

skills/react-devtools/references/profiling.md

@@ -0,0 +1,74 @@
+# React Native Profiling
+
+Use this workflow when the user reports slow interactions, excessive re-renders, unstable props, or unclear render causes.
+
+## Baseline
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools count
+agent-device react-devtools get tree --depth 3
+```
+
+If the app is not connected, run:
+
+```bash
+agent-device react-devtools start
+agent-device react-devtools wait --connected
+```
+
+Then reload or relaunch the React Native app if needed.
+
+## Capture One Interaction
+
+```bash
+agent-device react-devtools profile start "short label"
+# Trigger exactly the interaction being investigated.
+agent-device react-devtools profile stop
+```
+
+Keep the profiling window narrow. Extra navigation, warm-up work, or unrelated gestures make the report harder to interpret.
+
+## Identify Suspects
+
+```bash
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+- A component with high average render time is a slow-render suspect.
+- A component with high render count is a re-render suspect.
+- A component can be both.
+
+## Drill In
+
+```bash
+agent-device react-devtools profile report @c12
+agent-device react-devtools get component @c12
+```
+
+Use `profile report` to identify render causes and changed keys. Use `get component` to inspect current props, state, and hooks.
+
+Common interpretations:
+
+| Signal                                     | Meaning                             | Typical follow-up                              |
+| ------------------------------------------ | ----------------------------------- | ---------------------------------------------- |
+| `props-changed` with function props        | Parent may pass unstable callbacks  | Check whether the parent can use `useCallback` |
+| `props-changed` with object or array props | Parent may pass unstable references | Check whether the parent can use `useMemo`     |
+| `parent-rendered` with many child renders  | Child has no bailout                | Check whether `React.memo` is appropriate      |
+| `state-changed`                            | Component state caused the render   | Check whether the state update is necessary    |
+| `hooks-changed`                            | Hook value or dependency changed    | Inspect hook values and dependencies           |
+
+## Verify
+
+After making a change, repeat the same interaction:
+
+```bash
+agent-device react-devtools profile start "after fix"
+# Repeat the same interaction.
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+Compare render counts, average durations, changed keys, and commit counts against the baseline.

src/__tests__/cli-help.test.ts

@@ -95,6 +95,14 @@ test('appstate --help prints command help and skips daemon dispatch', async () =
   assert.match(result.stdout, /Global flags:/);
 });
 
+test('help react-devtools prints passthrough command help and skips daemon dispatch', async () => {
+  const result = await runCliCapture(['help', 'react-devtools']);
+  assert.equal(result.code, 0);
+  assert.equal(result.daemonCalls, 0);
+  assert.match(result.stdout, /Usage:\n  agent-device react-devtools \[\.\.\.args\]/);
+  assert.match(result.stdout, /React Native component trees/);
+});
+
 test('help unknown command prints error plus global usage and skips daemon dispatch', async () => {
   const result = await runCliCapture(['help', 'not-a-command']);
   assert.equal(result.code, 1);

src/__tests__/cli-react-devtools.test.ts

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import {
+  AGENT_REACT_DEVTOOLS_PACKAGE,
+  buildReactDevtoolsNpmExecArgs,
+} from '../cli/commands/react-devtools.ts';
+
+test('react-devtools passthrough pins agent-react-devtools package version', () => {
+  assert.equal(AGENT_REACT_DEVTOOLS_PACKAGE, 'agent-react-devtools@0.4.0');
+  assert.deepEqual(buildReactDevtoolsNpmExecArgs(['get', 'tree', '--depth', '3']), [
+    'exec',
+    '--yes',
+    '--package',
+    'agent-react-devtools@0.4.0',
+    '--',
+    'agent-react-devtools',
+    'get',
+    'tree',
+    '--depth',
+    '3',
+  ]);
+});
+
+test('react-devtools docs mention the pinned package version', () => {
+  const docs = ['README.md', 'website/docs/docs/commands.md', 'skills/react-devtools/SKILL.md'];
+
+  for (const file of docs) {
+    assert.match(fs.readFileSync(file, 'utf8'), new RegExp(AGENT_REACT_DEVTOOLS_PACKAGE));
+  }
+});