Genie React

How to debug a React app with Claude Code and prove the fix worked

Install Genie, run init to give Claude Code the skill, then follow one real bug from symptom to render cause to fix to a verify pass with exit code 0.

To debug a React app with Claude Code, give it two tools it can run from the terminal. A browser driver acts on the page, and Genie reports what React did and decides whether the fix held. You install Genie in the app, run npx genie-react init to add the skill, and ask Claude Code for the outcome, such as "find out why this re-renders, fix it, and verify the fix."

This page follows one real bug in the Meridian Ops dashboard (apps/realworld-dashboard in this repo). Ticking one order's checkbox re-rendered the sidebar. Each step shows the commands from the Genie skill's loop, as run in this repo, with their real output. The full log is in the evidence file.

Install Genie and the skill

From the app folder, install both packages:

pnpm add -D genie-react @genie-react/cli

You need both. genie-react holds the runtime, and @genie-react/cli holds the genie-react command. npm view shows that only the CLI package has a bin:

$ npm view genie-react@1.1.0 bin

$ npm view @genie-react/cli@1.1.0 bin
{ 'genie-react': 'dist/cli.js' }

The dashboard already lists both as dev dependencies, so the run starts at init. Trimmed to the artifacts, with the checkout path shown as <checkout>:

$ npx genie-react init
ok setup_completed: Setup changes are recorded in artifacts.
  framework: tanstack-router
  artifacts[7]:
    - {kind:vite_config,status:already,path:<checkout>/apps/realworld-dashboard/vite.config.ts}
    - {kind:root_route,status:already,path:<checkout>/apps/realworld-dashboard/src/routes/__root.tsx}
    - {kind:gitignore,path:<checkout>/apps/realworld-dashboard/.gitignore,status:applied}
    - {kind:agent_skill,path:<checkout>/apps/realworld-dashboard/.agents/skills/genie/SKILL.md,status:applied}
    - {kind:agent_skill,path:<checkout>/apps/realworld-dashboard/.agents/skills/genie/APP_TOOLS.md,status:applied}
    - {kind:agent_skill,path:<checkout>/apps/realworld-dashboard/.agents/skills/genie/EVIDENCE.md,status:applied}
    - {kind:agent_skill,path:<checkout>/apps/realworld-dashboard/.claude/skills/genie,status:applied,link:symlink}

init writes the skill to .agents/skills/genie and links .claude/skills/genie to it, which is where Claude Code looks for project skills. In the Claude Code session that ran these commands, the skill showed up as genie right after init. The Vite config and root route already had Genie, so init left them alone. Install and connect lists what init changes in other setups.

The installed skill calls the CLI as node_modules/.bin/genie-react, so the commands below use that path. The README says a wrapper such as npx or pnpm exec adds up to 350 ms to every call. Suggested commands in Genie's output start with the runner you used. When you call the binary directly, Genie takes the runner from the project's lockfile, so in this pnpm repo the next: lines read pnpm exec genie-react.

Ask for the outcome

Start the dev server, open the app with an agent-browser session, and check that Genie is connected. Use the same session name for both tools:

agent-browser --session upd-h open http://127.0.0.1:5244/orders
node_modules/.bin/genie-react status --session upd-h --wait 15000

status printed connected: true and ready: true. Then name the interaction and what you want:

Ticking an order's checkbox on the Orders page re-renders the sidebar. Find out why, fix it, and verify the fix.

The skill gives the agent a loop: open a window, act once, read the evidence, fix, and verify.

Reproduce once and read the render cause

The agent opens a render window for SidebarNav, ticks one row, and waits until React, Query and the router settle:

node_modules/.bin/genie-react call react_clear_renders '{"component":"SidebarNav"}' --session upd-h
agent-browser --session upd-h find role checkbox check --name 'Select SO-106000'
node_modules/.bin/genie-react call devtools_wait '{"condition":"settled","domains":["react","query","router"],"timeoutMs":10000}' --fail-on-result-error --session upd-h
node_modules/.bin/genie-react call react_render_causes '{"component":"SidebarNav","limit":20}' --session upd-h

The summary names one render, graded unnecessary, from an external store, and the store field that changed (trimmed):

SidebarNav #8736064143402 {renderEventId:render:10:1,documentCommitId:10,mountId:mount:1,necessity:unnecessary,necessityReason:output-unchanged,inputEvidence:none-observed,source:{location:/src/layout/app-shell.tsx:38:9,role:element-callsite,ownership:app}}
  ← external-store inferred anonymous-external-store {changedFields:[selectedOrderIds]}
coverage:
  complete: true

output-unchanged means the render wrote nothing to the DOM. The sidebar never shows the selection, yet a change to selectedOrderIds re-rendered it. Genie 1.0.2 printed the changed field only with "view":"full", and 1.1.0 prints it in the default view.

Find the line

source points at app-shell.tsx:38, where AppShell renders <SidebarNav>. The component lives in src/layout/sidebar-nav.tsx, and it reads the zustand store like this:

src/layout/sidebar-nav.tsx
const { recentlyViewed } = useWorkspaceStore()

Calling a zustand hook with no selector subscribes the component to the whole store. Ticking a checkbox writes a new selectedOrderIds set, so every subscriber without a selector renders.

Write the claims before the fix

Before changing code, the agent records a failing verdict. begin fixes the claims:

  • render SidebarNav max 0 says the sidebar must not render.
  • render BulkActionBar min 1 says the toolbar that shows the selection must render. This is the positive control. If the click misses, this claim fails the run instead of leaving only a refusal.
  • boundaries clean says no error boundary catches anything.
agent-browser --session upd-h reload
node_modules/.bin/genie-react verify begin --session upd-h --name 'select one order' \
  --claim 'render SidebarNav max 0' --claim 'render BulkActionBar min 1' --claim 'boundaries clean'
agent-browser --session upd-h find role checkbox check --name 'Select SO-106000'
node_modules/.bin/genie-react verify end vfy_ca6cec22-2bae-4196-a1c9-39ef31c54fe6 --session upd-h

Trimmed to the verdict and claim lines:

fail vfy_ca6cec22-2bae-4196-a1c9-39ef31c54fe6 "select one order"  11 commits, quiet after 884 ms (react, query, router, network)
  1 fail render SidebarNav max 0  {renders:1,mounts:0,updates:1,remounts:0,semantics:exact,instances:1,activeInstances:1}
  2 pass render BulkActionBar min 1  {renders:1,mounts:0,updates:1,remounts:0,semantics:exact,instances:1,activeInstances:1}
  3 pass boundaries clean  {caughtDuringWindow:0,caughtAtEnd:0}

The command exited 1. network in the verdict line means verify also waited for the app's own requests to finish before it decided.

Apply the fix

Select only the field the sidebar shows:

--- a/apps/realworld-dashboard/src/layout/sidebar-nav.tsx
+++ b/apps/realworld-dashboard/src/layout/sidebar-nav.tsx
 export function SidebarNav({ collapsed, onToggle }: { collapsed: boolean; onToggle: () => void }) {
-  const { recentlyViewed } = useWorkspaceStore()
+  const recentlyViewed = useWorkspaceStore((state) => state.recentlyViewed)

This is the reference fix from the dashboard's answer key. The run applied it and reverted it afterwards with git checkout.

Prove it with the same claims

The agent reloads the page, so no selection carries over, and runs the same begin, the same click and end. Trimmed:

pass vfy_a080db08-8413-4f17-b45d-78b38765c9a0 "select one order"  10 commits, quiet after 1498 ms (react, query, router, network)
  1 pass render SidebarNav max 0  {renders:0,mounts:0,updates:0,remounts:0,semantics:exact,instances:1,activeInstances:1}
  2 pass render BulkActionBar min 1  {renders:1,mounts:0,updates:1,remounts:0,semantics:exact,instances:1,activeInstances:1}
  3 pass boundaries clean  {caughtDuringWindow:0,caughtAtEnd:0}
! ui-outcome-not-observed: Genie does not check the screen; confirm it with the UI driver
attempt 2 for these claims on this tab; previous fail vfy_ca6cec22-2bae-4196-a1c9-39ef31c54fe6; document reloaded since

The command exited 0. The sidebar rendered zero times, and the toolbar still rendered once. Genie does not check pixels, so the agent asks the driver what the toolbar shows:

$ agent-browser --session upd-h snapshot -s '[aria-label="Bulk actions"]'
- toolbar "Bulk actions"
  - StaticText "1"
  - StaticText " selected"
  - button "Mark shipped" [ref=e189]
  - button "Put on hold" [ref=e190]
  - button "Cancel" [ref=e191]
  - button "Clear selection" [ref=e192]

A good report from Claude Code quotes both verdict lines, the failing ID and the passing ID, and the driver's check of the screen.

When this approach does not fit

  • verify counts renders and checks effects and error boundaries. It does not measure time. For timing before and after a change, see Optimize.
  • react_render_causes graded the store cause inferred, not exact. The changed field and the store call in sidebar-nav.tsx were enough here. When a cause is only inferred, read the code before you act on it.
  • Genie needs a development build of React 18 or newer and the dev-server setup from Install and connect.

Use it with your agent covers the skill and running several agents at once. Verify a fix lists every claim form. For how this compares with what a browser driver sees on its own, see What is an agentic React tool?

On this page