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/cliYou 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 15000status 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-hThe 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: trueoutput-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:
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 0says the sidebar must not render.render BulkActionBar min 1says 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 cleansays 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-hTrimmed 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 sinceThe 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
verifycounts renders and checks effects and error boundaries. It does not measure time. For timing before and after a change, see Optimize.react_render_causesgraded the store causeinferred, notexact. The changed field and the store call insidebar-nav.tsxwere 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?
What is an agentic React tool? What your coding agent can't see from the browser
An agentic React tool is one your coding agent runs from the terminal and reads as text. Real runs show what a browser driver saw in a React app, and what Genie added.
Give Cursor, Codex, and Copilot a view inside your running React app
One init command gives Cursor, Codex and Copilot a Genie skill for AI React debugging. Here is the setup each agent's docs confirm, and a real verify run.