Genie React

Live DevTools for your running React + TanStack app — driven from the terminal by your AI agent, through one CLI.

AI coding agents work blind: they read source code and guess what the running app does. Genie removes the guessing. It connects your agent (Claude Code, Codex, OpenCode, …) to the app's live DevTools — React internals, TanStack Query, TanStack Router, and any custom devtools built on TanStack — so the agent can see what's happening and act on it.

That closes the loop. The agent makes a change, checks the real app, and confirms the change works — finds what's slow, fixes it, proves the fix — without you relaying screenshots or console output.

One command drives everything:

genie-react call <tool> '<json>'

Install

Dev-only. Never ships to production.

pnpm add -D genie-react     # everything app-side: collectors, <Genie />, Vite plugin, hub
npx @genie-react/cli init   # detects your setup and wires it
pnpm dev                    # start your app

init adapts to your framework. The same tools work everywhere.

Vite

Covers TanStack Start, plain React, and any Vite-based framework. init adds the genie() plugin: the hub rides the dev server (loopback only, no extra port) and the client is injected automatically. Router/Start apps also get one line near the app root:

import { Genie } from 'genie-react'

{import.meta.env.DEV && <Genie />}

<Genie /> finds your Router and QueryClient on its own. If yours live somewhere unusual, pass them in: <Genie queryClient={queryClient} router={router} />.

Next.js

init adds <GenieScript /> to your root layout and creates instrumentation.ts, which starts a standalone hub alongside next dev. The hub serves the browser client to the page as one classic script.

Other bundlers (CRA, Parcel, Rsbuild, …)

Run npx @genie-react/cli hub and add one line first in <head>:

<script src="http://localhost:4390/__genie/client.js"></script>

The tag ships the React + memory tools. To add the Query/Router tools, compose the client in your own bundle instead, passing your own instances:

import 'genie-react/hook' // first import, before React
import { createGenieClient, reactCollector, sessionCollector } from 'genie-react/client'
import { memoryCollector, queryCollector } from 'genie-react/collectors'
import { queryClient } from './query-client' // the instance your <QueryClientProvider> renders with

createGenieClient({
  url: 'ws://localhost:4390/__genie/ws',
  collectors: [sessionCollector(), reactCollector(), memoryCollector(), queryCollector(queryClient)],
}).start()

React Native / Expo

genie-react/native wires the DOM-free collectors (React, memory, perf, plugins) and takes your TanStack instances by value, so it loads under Metro whether or not TanStack is installed. Needs Metro with package.json exports enabled (React Native 0.79+ / Expo SDK 53+).

Run the hub on your dev machine (npx @genie-react/cli hub), then start Genie from your app entry, dev-only:

import { Genie } from 'genie-react/native'

// iOS simulator: 127.0.0.1, Android emulator: 10.0.2.2, physical device: your machine's LAN IP
// Use 127.0.0.1, not localhost — the hub binds IPv4 loopback, and some runtimes resolve localhost to IPv6 (::1) first.
{__DEV__ && <Genie url="ws://127.0.0.1:4390/__genie/ws" />}

Or start it imperatively (e.g. in index.js, before registerRootComponent): if (__DEV__) startGenie({ url: 'ws://127.0.0.1:4390/__genie/ws' }). Pass queryClient / router on any render to add the Query/Router tools — Genie registers them onto the running client.

Almost everything works as on the web. The differences: react_dom_for_component reports native views with their testID / accessibility props (there are no CSS selectors); browser_get_memory needs RN 0.85+ (Hermes exposes performance.memory there); react_component_for_dom needs a DOM and is unavailable.

Drive it

npx @genie-react/cli status                    # connected once a browser opens the app
npx @genie-react/cli tools                     # group index; drill in: tools <group> / tools <tool>
npx @genie-react/cli call react_get_renders '{"sort":"renders"}'
npx @genie-react/cli call query_list '{}'
npx @genie-react/cli call router_navigate '{"to":"/dashboard"}'

npx @genie-react/cli doctor checks the wiring; doctor --live also probes the running hub, the served client, and a session round-trip. Stale .genie/bridge.json files left by a killed dev server are cleaned up automatically.

Try a change before it ships

Every pull request and every push to main publishes preview builds to pkg.pr.new — no npm release required. The Preview Release workflow comments ready-to-copy URLs on each PR:

pnpm add -D https://pkg.pr.new/genie-react@<sha>
npx https://pkg.pr.new/@genie-react/cli@<sha> status

Give your agent the skill

Install the agent skill so your agent knows when and how to use Genie:

npx skills add y0u-0/genie-react

Use with agent-browser & agent-device

Genie is the eyes — it reads what happens underneath the pixels: renders, effects, hooks, queries, errors no screenshot can show. Pair it with the hands that drive the UI:

Web — agent-browser opens the app, clicks, types, and takes screenshots.
React Native — agent-device taps, types, and screenshots the simulator or device.

Together your agent closes the loop on its own: make a change, drive the app, read why, then fix or optimize — verifying its own work end to end.

What you get

See —

the component tree; find components by name
a component's props, state, hooks (each labeled: state / reducer / memo / callback / ref / effect), and the contexts it consumes
the DOM node(s) a component renders, each with a selector
what re-rendered, how often, and why — including unstable props that defeat memo
which effects fired and why — catches refetch / setState loops
caught errors and suspended boundaries — why a screen is blank or stuck
a profiler: slowest, most re-rendered, most wasted on unstable props
the TanStack Query cache: staleness, observers, refetch storms, cache churn
the Router: state, matches, params, loaders
the browser JS heap

Do —

navigate, preload, and invalidate routes
invalidate / refetch / reset / remove / setData / cancel / fetch / ensure queries
re-run a mutation
override a component's props, hook state, or a context value
force a Suspense fallback or an error boundary — hold loading / error UI open to inspect it, no code edits
list every active override and reset them all
snapshot render aggregates and diff later: a regressed / improved verdict that proves (or reverts) a perf fix

Tools

61 tools in 7 groups. read tools are safe to call freely; action tools mutate the running app. Each tool documents itself — tools <group> lists a group, tools <tool> prints the full schema — so here are just the names:

React — read: react_get_tree, react_find_components, react_inspect_component, react_inspect_context, react_dom_for_component, react_component_for_dom, react_get_renders, react_clear_renders, react_effect_audit, react_error_state, react_profile_start, react_profile_stop, react_profile_report, react_profile_snapshot, react_renders_diff, react_list_overrides. action: react_override_props, react_override_hook_state, react_override_context, react_toggle_suspense_fallback, react_force_error_boundary, react_reset_overrides.

Query — read: query_list, query_get, query_get_data, query_is_fetching, query_list_mutations, mutation_get. action: query_invalidate, query_refetch, query_cancel, query_reset, query_remove, query_clear, query_set_data, query_fetch, query_ensure, mutation_rerun.

Router — read: router_get_state, router_list_matches, router_list_routes, router_build_location, router_match_route. action: router_navigate, router_preload, router_load, router_invalidate, router_clear_cache, router_history.

Plugin passthrough — read: plugin_list, plugin_get_events. action: plugin_emit. Discovery is traffic-based; declare silent plugins up front with <Genie plugins={['cart-devtools']} /> so they're listed before their first event.

Memory — read: browser_get_memory, browser_measure_memory (Chromium only).

Perf — read: browser_fps (frame-rate sample with a smooth / degraded / janky verdict).

Meta — read: devtools_status, devtools_wait.

How it works

Collectors in the browser (React, Query, Router, plugins, memory) run tool calls against the real fibers and caches, and talk over a WebSocket to a small hub — embedded in your Vite dev server, or standalone (genie-react hub / Next.js instrumentation.ts), where it also serves the browser client as a single script. The CLI connects to that hub, runs tools, and prints JSON.

Several tabs, apps, and agents coexist. Calls hit the most recent tab; genie-react status lists every session, and --session <id> targets a specific tab (set GENIE_SESSION once per agent shell to pin an agent to its tab). A standalone hub identifies the app it serves, so a second app's hub walks to the next free port instead of cross-connecting, and each app's .genie/bridge.json pins its CLI to its own hub.

Dev-only and local: the Vite plugin is inert in production builds, the browser client only starts under import.meta.env.DEV, and the hub listens on localhost only.

Packages

Package / export	What it is
`genie-react`	`<Genie />` component
`genie-react/vite`	Vite plugin
`genie-react/script`	`<GenieScript />` for any SSR root layout
`genie-react/next`	Next.js helpers
`genie-react/native`	React Native / Expo entry
`genie-react/client`, `genie-react/hook`	the injected browser client
`genie-react/collectors`	every collector, for manual composition
`genie-react/hub`	the WebSocket hub
`genie-react/protocol`	the wire protocol
`@genie-react/cli`	the agent interface: `init` / `doctor` / `link`, `status` / `tools` / `call`