@genie-react/cli

中文文档
1.0.2发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 7460

Give AI coding agents live React and TanStack DevTools from the terminal. Inspect, optimize, test, and verify a running app.

原始使用文档
文档目录7 节
  1. Start
  2. Find wasted renders
  3. Audit an effect
  4. Inspect live hooks
  5. Test a TanStack state
  6. Output for agents
  7. Compare repeated runs

Genie CLI

Give your coding agent DevTools for the running React app.

The CLI lets the agent inspect, optimize, test, and verify the app from the terminal.

Start

pnpm add -D genie-react
npx @genie-react/cli init
pnpm dev
npx @genie-react/cli status --sessions-only

If more than one tab is open, open yours with agent-browser --session my-agent open <url> (or add ?_genie=my-agent to the URL in another browser). Then pass --session my-agent to each command.

The alias survives navigation, reloads, and reconnects. From a workspace root, the CLI selects one live app or stops with an explicit list when several are live.

Find wasted renders

npx @genie-react/cli call react_clear_renders '{}'
# Drive one flow in the app.
npx @genie-react/cli call react_get_renders '{"sort":"selfTime","limit":3}'
npx @genie-react/cli call react_render_causes '{"component":"Button","limit":3}'

Use the observation only when its coverage is complete and budgetExhaustedCommits is zero. The default adaptive budget grows to fit the tree mounted when you clear. When a limit still skips work, coverage.budgetAdvice names it and suggests a budget: clear with that budget and repeat the step, because growth on later commits cannot restore evidence skipped by the commit that ran out.

Excerpt of real react_render_causes output from the Vite demo:

events[5] (componentName #componentId {fields}, then ← kind evidence name {fields} per cause):
  each: {mountId:mount:9,source:{location:App.tsx:234:6,ownership:app}}
  TaskPanel #57 {renderEventId:render:13:184,documentCommitId:13,inputEvidence:changed}
    ← query exact "[\"tasks\"]" {reason:query-notification-delivered,changedResultFields:[data,dataUpdatedAt]}
    ← external-store inferred tanstack-mutation-observer
  TaskPanel #57 {renderEventId:render:10:149,documentCommitId:10,inputEvidence:none-observed}
    ← parent inferred App
coverage:
  complete: true
  inputAttributionComplete: true
  semantics: exact

The agent gets the component, source location, and each cause with its evidence grade: exact, inferred, or unknown. Causes include props, state, context, Query, Router, parent renders, and mounts.

Audit an effect

npx @genie-react/cli call react_effect_audit '{"appOnly":true,"onlyHot":true}'

Each effect reports its own source and whether ownership evidence is exact, inferred, or unknown. Hotness uses a minimum sample count and a 95% interval, so a short run is marked insufficient-data.

Inspect live hooks

npx @genie-react/cli call react_find_components '{"query":"App","exact":true}'
# Use the id returned above. The Vite demo returned TaskPanel #57.
npx @genie-react/cli call react_inspect_component '{"id":57}'

Excerpt from the Vite demo:

id: 57
name: TaskPanel
kind: function
props: {}
hooks[29]:
  - {index:0,kind:state,stateful:true,stateIndex:0,value:admin}
  - {index:1,kind:state,stateful:true,stateIndex:1,value:""}
  - {index:6,kind:effect,stateful:false,customHooks:[useQuery,useBaseQuery],deps:["ƒ anonymous()"]}

The agent can read the mounted component's real props, state, and hooks instead of guessing from source.

Test a TanStack state

npx @genie-react/cli call query_simulate_state \
  '{"queryKey":["demo","greeting"],"state":"pending"}'
ok: true
queryHash: "[\"demo\",\"greeting\"]"
simulatedState: pending
originalStatus: success

The agent can drive and verify the real loading UI, then restore the exact query state:

npx @genie-react/cli call query_restore_state '{"queryKey":["demo","greeting"]}'
ok: true
restored: 1

Output for agents

Every command prints compact text by default. It keeps every field of the result, quotes app strings so they cannot fake a line, and costs fewer tokens than the same JSON: about 72% of the tokens across the recorded results, 42–60% for a component tree. Add --json for the JSON document:

npx @genie-react/cli call react_inspect_component '{"id":57}' --json

Use --fields when the agent only needs a few fields:

npx @genie-react/cli call query_list '{}' --fields queryHash,status,fetchStatus
[1]:
  - {queryHash:"[\"demo\",\"greeting\"]",status:success,fetchStatus:idle}

Every tool includes its input schema and a runnable example:

npx @genie-react/cli tools
npx @genie-react/cli tools react_inspect_component

A failure starts with error <reason>: <message>, then next: $ <command> when a recovery command is known. --json prints one compact JSON value instead, with the same fields. batch prints one block per result under a [n/total] tool ok|error header; batch --json prints one JSON array and batch --ndjson prints JSONL.

Scripts that parse output add --json, or set GENIE_OUTPUT=json once to keep the 0.19 output, JSONL included. CLI-owned status, batch, and error objects include schemaVersion in JSON. Successful calls keep the output schema shown by tools <tool>. The output contract specifies the text format.

Use --verbose when startup is unclear. It prints the CLI version, bridge target, session, and time budgets to stderr. --connect-timeout <ms> bounds only the bridge connection.

Wait on an exact Query key instead of sleeping:

npx @genie-react/cli call devtools_wait \
  '{"condition":"query-settled","queryKey":["demo","greeting"]}'

For a large component tree, call react_find_components, then pass its id as rootId to react_get_tree.

Compare repeated runs

Clear the render data, drive one exact flow, and create a named capture:

npx @genie-react/cli call react_clear_renders '{}'
# Drive the flow.
npx @genie-react/cli call devtools_capture_create '{"name":"before-1"}' --json

Discard a capture whose React coverage is incomplete or budget-exhausted rather than comparing a lower-bound observation.

Run the same flow at least three times before and after the change. Then compare the returned IDs:

npx @genie-react/cli call devtools_capture_compare \
  '{"baselineCaptureIds":["<before-1>","<before-2>","<before-3>"],"candidateCaptureIds":["<after-1>","<after-2>","<after-3>"],"metrics":["react.renders"],"budgets":[{"metric":"react.renders","maxRegressionPct":0}]}'

The verdict is pass, fail, or insufficient-data. It also reports sample counts, median, p95, and spread. The hub keeps the latest 20 captures.

See the full setup and tool list.

版本与发布记录

@genie-react/cli 共发布 35 个版本,首次发布于 2026/07/02;过去 12 个月发布了 35 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.0.2latest2026/11/16今天
1.0.12026/11/16今天
1.0.02026/11/16今天
0.19.02026/10/1927 天前
0.18.12026/10/1927 天前
0.18.02026/10/1927 天前

关于 @genie-react/cli 的常见问题

@genie-react/cli 是什么?

Give AI coding agents live React and TanStack DevTools from the terminal. Inspect, optimize, test, and verify a running app.

如何安装 @genie-react/cli?

在项目目录运行 npm install @genie-react/cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 genie-react,可以用 npx genie-react 直接运行。

@genie-react/cli 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@genie-react/cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@genie-react/cli 可以商用吗?

@genie-react/cli 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@genie-react/cli 的下载量有多少?

根据 npm 官方下载统计,@genie-react/cli 在 2026/10/16 – 2026/11/14 这 30 天内被下载 7,460 次,日均约 249 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@genie-react/cli 还在维护吗?

最新版本 1.0.2 发布于 2026/11/16(今天);至今共发布 35 个版本,其中过去 12 个月发布了 35 个;首次发布于 2026/07/02。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。