Deterministic React code scanner that installs as an agent skill
React Doctor is a deterministic React code-quality scanner built for AI coding agents. It analyzes a codebase via CLI and flags issues across state/effects, performance, architecture, security, accessibility, and maintainability, including overly complex functions and repeated JSX that should be extracted. Instead of relying on LLM guesswork, it produces reproducible audit results. The findings can be installed as an agent skill for Claude Code, Cursor, Codex, OpenCode and similar tools, so the same rules guide future fixes. It also ships a GitHub Actions CI mode that only reports issues introduced by the current pull request, and can record Chrome performance traces for runtime hotspots. A good fit for teams whose React code is partially written by agents, or any engineering team that wants a low-noise React quality gate in CI.
React Doctor is a deterministic React code scanner that you run at your project root to get an audit. It is built for developers and AI coding agents: once the audit is available, the same tool can install an agent skill so your assistant learns from the issues and fixes them going forward. The project is MIT-licensed and maintained under the millionco umbrella.
React Doctor 是一个确定性的 React 代码扫描器，在项目根目录运行即可拿到一份审计报告。它同时面向开发者和 AI 编码助手：拿到审计后，同一个工具还能把问题装上 agent 技能，让助手学习这些坏味道并在后续修复。项目采用 MIT 协议，由 millionco 维护。
LLM-based reviews can be inconsistent; React Doctor deliberately scans deterministically. It catches issues across state and effects, performance, architecture, security, accessibility, and maintainability. It also points out overly complex React functions and repeated JSX trees as composition candidates, giving agents and humans concrete targets to refactor.
基于 LLM 的代码评审常常时好时坏；React Doctor 刻意采用确定性扫描。它覆盖 state/effects、性能、架构、安全、可访问性和可维护性等类别，并会标出过于复杂的 React 函数和重复出现的 JSX 树，作为提取组合（composition）的候选，让 agent 或人都有清晰的重构目标。
The scanner is rule-based, so the same code always produces the same findings. Rules span multiple concerns rather than just one linter dimension. The repo structure shows it ships both an ESLint plugin (packages/eslint-plugin-react-doctor) and an oxlint plugin (packages/oxlint-plugin-react-doctor), with a shared core (packages/core) and a public CLI (packages/react-doctor).
扫描器基于规则，因此相同代码永远得到相同结论。规则不止覆盖单一 lint 维度，而是横跨多个关注点。从仓库结构可以看出，它同时提供 ESLint 插件（packages/eslint-plugin-react-doctor）和 oxlint 插件（packages/oxlint-plugin-react-doctor），核心引擎在 packages/core，公开 CLI 在 packages/react-doctor。
Once you have an audit, run npx react-doctor@latest install to register a skill for your coding agent. The README lists Claude Code, Cursor, Codex, OpenCode, and more. This turns a one-off audit into an ongoing capability: your agent can consult the findings and avoid repeating them.
拿到审计结果后，运行 npx react-doctor@latest install 即可为你的编码助手安装一个技能。README 列出 Claude Code、Cursor、Codex、OpenCode 等。这样一次性的审计就变成了持续能力：agent 可以参考这些问题，避免重蹈覆辙。
React Doctor reviews every pull request and reports only the issues your change introduced, not your existing backlog. npx react-doctor@latest ci install adds the workflow, scans every pull request, and posts a summary comment. You can tune gate, scope, and comments with react-doctor ci config, and bump the action with react-doctor ci upgrade. GitHub Actions is fully supported; GitLab CI gets a gate-only scaffold.
React Doctor 会审查每个 pull request，并且只报告你这次改动引入的问题，而不是历史存量。npx react-doctor@latest ci install 会添加 workflow，扫描每个 PR 并发布一条汇总评论。你可以用 react-doctor ci config 调整门禁、扫描范围和评论，用 react-doctor ci upgrade 升级 action。GitHub Actions 完整支持，GitLab CI 提供仅门禁版的脚手架。
Beyond static analysis, React Doctor can capture a Chrome DevTools performance trace while you interact with a running app. npx react-doctor@latest scan http://localhost:3000 opens system Chrome in an isolated profile, records until you press Enter (max five minutes), and flashes purple outlines with component names as React renders. The output is a readable summary plus the path to a compressed trace. For authenticated sessions, start a dedicated Chrome profile with remote debugging and pass its endpoint via --cdp. The trace stays local and is never uploaded, but it may contain page URLs, source paths, and React profiling details, so treat it as sensitive.
除静态分析外，React Doctor 还能在你与运行中的应用交互时录制 Chrome DevTools performance trace。npx react-doctor@latest scan http://localhost:3000 会以隔离配置打开系统 Chrome，录到按回车为止（最长五分钟），并在 React 渲染时用紫色外框标出组件名。输出是一份易读摘要和压缩 trace 的路径。需要复用登录态时，可以启动带 remote debugging 的专用 Chrome profile，通过 --cdp 传入地址。trace 只保存在本地，不会上传，但可能包含页面 URL、源码路径和 React profiling 细节，应按敏感数据处理。
The quickest start is a one-liner: npx react-doctor@latest at your project root. From there, the flow branches by need: install the agent skill (npx react-doctor@latest install), set up CI (npx react-doctor@latest ci install), or scan a running app. Rules can be configured in doctor.config.ts.
最快上手就是一行：在项目根目录运行 npx react-doctor@latest。之后按需选择路径：安装 agent 技能（npx react-doctor@latest install）、接入 CI（npx react-doctor@latest ci install）、或扫描运行中的应用。规则可以在 doctor.config.ts 中配置。
React Doctor fits teams that want consistent, deterministic React checks integrated into agents and CI, across Next.js, Vite, Astro, TanStack, React Native, Expo, and more. Keep in mind: telemetry is on by default (CLI version, commands, framework, React version, project size, rule counts — no file contents) and can be disabled with npx react-doctor@latest --no-telemetry. In an interactive terminal you can run react-doctor scan without a URL and pick a local app; agents and CI must pass the URL explicitly. Because it is rule-based, it catches concrete anti-patterns rather than offering free-form LLM judgment.
React Doctor 适合那些希望在 agent 和 CI 中获得稳定、确定性 React 检查的团队，支持 Next.js、Vite、Astro、TanStack、React Native、Expo 等。需要注意：遥测默认开启（收集 CLI 版本、命令、框架、React 版本、项目大小、命中规则名与计数——不收集文件内容），可用 npx react-doctor@latest --no-telemetry 关闭。在交互终端里可以不带 URL 运行 react-doctor scan 并选择本地应用；agent 和 CI 则必须显式传入 URL。由于基于规则，它抓的是具体的反模式，而不是自由发挥的 LLM 判断。