# Genie React

> Live React and TanStack DevTools for AI coding agents. Find performance problems, test app states, and verify fixes end to end.

Genie React is a local-first developer tool: the genie-react npm package adds collectors and a hub to a running React or React Native app, and the @genie-react/cli package (`npx genie-react`) gives an AI coding agent DevTools access to that app from the terminal. Every link below points at markdown; the same pages are served as HTML without the .md suffix.

## When to use Genie React

Use Genie React when an AI coding agent works on a live React or TanStack app and needs runtime evidence instead of guesses:

- Debug why a component rendered: join one UI action to its hook changes, renders, effects, and source locations.
- Optimize render performance: find expensive components, prove a fix with before/after runs, and check memory and frame rate.
- Read and manipulate live state: props, hooks, Context, TanStack Query cache, and TanStack Router navigation.
- Test hard-to-reach UI states: force loading and error branches, verify the UI, then restore the app.
- Verify a fix end to end: pair Genie with a UI driver (agent-browser or agent-device) so the agent drives the UI and checks the result against live evidence.

Do not reach for Genie React for static code analysis, non-React apps, or production monitoring — it attaches to a locally running development app.

How to call it: run `npx genie-react` in the app repository, then follow [Getting started](https://genie-react.com/docs/getting-started/index.md). The full tool list an agent can call is under [Tools](https://genie-react.com/docs/tools/index.md).

## Machine-readable resources

- [llms-full.txt](https://genie-react.com/llms-full.txt): the complete documentation as one markdown file.
- [openapi.json](https://genie-react.com/openapi.json): OpenAPI 3.1 description of this site's HTTP endpoints.
- [sitemap.xml](https://genie-react.com/sitemap.xml): every indexable URL.
- [GitHub repository](https://github.com/Genie-sa/genie-react): source code, issues, and releases.

## Overview

- [Case studies](https://genie-react.com/docs/case-studies.md): Real flows verified against the Genie demo apps.
- [Getting started](https://genie-react.com/docs/getting-started.md): Connect Genie to a running app and make the first live call.
- [Genie React](https://genie-react.com/docs/index.md): Live React and TanStack DevTools for coding agents.
- [Setup by platform](https://genie-react.com/docs/setup.md): Add the hub, browser client, and app collectors.
- [Tool reference](https://genie-react.com/docs/tools.md): Inputs, outputs, limits, and agent use for every live Genie tool.
- [Workflows](https://genie-react.com/docs/workflows.md): Small command sequences that answer one runtime question.

## Case studies

- [Check list render scope](https://genie-react.com/docs/case-studies/list-render-scope.md): Separate updated, idle, and unmounted keyed rows.
- [Measure the loading-state height gap](https://genie-react.com/docs/case-studies/loading-layout-shift.md): Hold Query pending, measure both layouts, and choose a fix.
- [Keep agents on separate tabs](https://genie-react.com/docs/case-studies/multi-agent-sessions.md): Use a stable alias across reloads and fail safely on duplicates.
- [Verify a native app end to end](https://genie-react.com/docs/case-studies/native-end-to-end.md): Press the real UI, explain its render, and prove Query cache delivery on iOS.
- [Check optimization evidence](https://genie-react.com/docs/case-studies/prove-an-optimization.md): Compare repeated runs and refuse to call incomplete evidence a win.
- [Prove Query cache to UI](https://genie-react.com/docs/case-studies/query-end-to-end.md): Change one cache entry, join its observer notification to a render, and restore real data.
- [Trace one interaction end to end](https://genie-react.com/docs/case-studies/render-and-effect.md): Join one browser action to its renders, causes, effects, and coverage.
- [Verify routes and forced states](https://genie-react.com/docs/case-studies/router-and-live-states.md): Check Router history, props, Suspense, and error boundaries.
- [Verify hard-to-reach UI states](https://genie-react.com/docs/case-studies/verify-ui-states.md): Read component and Context values, force variants, and return screenshots.

## Getting started

- [Autonomous agent workflow](https://genie-react.com/docs/getting-started/agent-workflow.md): Pair a UI driver with Genie so the agent can reproduce, fix, and verify the work.
- [CLI output](https://genie-react.com/docs/getting-started/cli-output.md): Pick compact text, JSON, JSONL, or selected fields.
- [First live check](https://genie-react.com/docs/getting-started/first-check.md): Drive one browser action, read its renders, verify the UI, and clean up.
- [Install](https://genie-react.com/docs/getting-started/install.md): Add Genie and let the CLI wire it into the app.
- [Sessions and tabs](https://genie-react.com/docs/getting-started/sessions.md): Keep every agent attached to the correct running tab.

## Reference

- [Leave the app clean](https://genie-react.com/docs/reference/cleanup.md): Restore temporary Query and React state after a test.
- [CLI commands](https://genie-react.com/docs/reference/cli.md): Setup, discovery, live calls, and machine output.
- [Read evidence safely](https://genie-react.com/docs/reference/evidence.md): Know what Genie observed, inferred, missed, or could not prove.
- [Packages and exports](https://genie-react.com/docs/reference/packages.md): Choose the package entry point for each setup.
- [Troubleshooting](https://genie-react.com/docs/reference/troubleshooting.md): Fix connection, readiness, targeting, and incomplete-result problems.

## Setup

- [Next.js](https://genie-react.com/docs/setup/nextjs.md): Start the local hub and load the client before the app runs.
- [Other web bundlers](https://genie-react.com/docs/setup/other-web.md): Use the standalone hub and load the React hook before React.
- [React Native and Expo](https://genie-react.com/docs/setup/react-native.md): Connect the repository Expo demo to the local hub.
- [Vite and TanStack Start](https://genie-react.com/docs/setup/vite.md): Run the hub through the Vite plugin and add app collectors.

## Tools

- [App tools](https://genie-react.com/docs/tools/app-tools.md): Tools the app registers itself — domain actions and queries agents call like built-ins.
- [Browser metrics](https://genie-react.com/docs/tools/browser.md): Measure page memory and frame performance around a real browser flow.
- [Plugins](https://genie-react.com/docs/tools/plugins.md): Discover, read, and emit TanStack DevTools plugin events.
- [Query actions](https://genie-react.com/docs/tools/query-actions.md): Refetch, reset, replace, and simulate TanStack Query state in the live app.
- [Query reads](https://genie-react.com/docs/tools/query-reads.md): Inspect TanStack Query cache data, observers, fetches, and mutations.
- [React actions](https://genie-react.com/docs/tools/react-actions.md): Test prop, hook, Context, Suspense, and error states in the live app.
- [Renders, effects, and profiling](https://genie-react.com/docs/tools/react-renders-and-effects.md): Measure React work, render causes, effect schedules, errors, and before/after changes.
- [React tree and state](https://genie-react.com/docs/tools/react-tree-and-state.md): Find mounted instances, inspect hooks and Context, and map React to DOM.
- [Router](https://genie-react.com/docs/tools/router.md): Inspect and drive TanStack Router routes, matches, history, loaders, and cache.
- [Sessions and captures](https://genie-react.com/docs/tools/sessions-and-captures.md): Check readiness, wait for runtime state, and compare saved runs.

## Workflows

- [Components, hooks, and Context](https://genie-react.com/docs/workflows/components-and-context.md): Read and test the state used by one mounted component.
- [Effects](https://genie-react.com/docs/workflows/effects.md): Find repeatedly scheduled effects and the hook that owns them.
- [Loading and error states](https://genie-react.com/docs/workflows/loading-and-errors.md): Hold brief branches still, verify them, and restore the app.
- [Memory and frame rate](https://genie-react.com/docs/workflows/memory-and-fps.md): Read browser heap signals and measure visible animation work.
- [Check a performance change](https://genie-react.com/docs/workflows/performance-proof.md): Compare equivalent flows and reject weak or incomplete evidence.
- [TanStack Query](https://genie-react.com/docs/workflows/query.md): Read cache state, wait for one exact key, and test loading or error UI.
- [Optimize renders](https://genie-react.com/docs/workflows/render-optimization.md): Find the expensive component, its observed cause, and a safe fix.
- [TanStack Router](https://genie-react.com/docs/workflows/router.md): Compare Router and browser state, build locations, and test navigation.