react-doctor: the React health check that talks to coding agents
It turns framework-aware linting, dead-code analysis, and agent-ready skills into one score, so teams can fix the right problems first.
- react-doctor turns React quality into triage by collapsing many diagnostics into one score that tells teams where to start.
- Its edge is the blend of framework-aware linting, dead-code analysis, and severity weighting, not any single rule.
- The `.ami/skills` layer makes the repo useful to coding agents, not just humans reading a report.
- The score is best treated as a baseline and CI gate, because a number cannot replace judgment.
A diagnosis, not a lint dump
Most lint tools hand you a long scroll of violations. react-doctor tries to compress that mess into a medical chart: one score, one severity system, one baseline for the whole React app.
That changes the conversation. Teams are not asking, "What failed?" They are asking, "What should we fix first?" The answer comes from combining framework-aware linting, dead-code detection, and a scoring layer that converts all of it into a single readout.
The pitch is simple: `npx -y react-doctor@latest .` at your project root. You get a number. If the number is low, you feel bad. Then (and here's where it gets interesting) you can hand that diagnostic output directly to an AI coding agent and tell it to fix things.
From Million.js to a doctor for React
react-doctor makes sense once you place it next to Aiden Bai's earlier work on Million.js and React Scan. Those projects already treated React as something worth profiling, questioning, and optimizing with strong opinions.
This repo pushes that instinct one step earlier in the lifecycle. Instead of only spotting runtime pain or rendering overhead, it tries to catch the structural issues that make React codebases harder to reason about, slower to evolve, and more expensive for agents to touch safely.
How react-doctor builds the score
The engine starts with project discovery. It checks what kind of React stack it is looking at, such as Next.js, React Native, or a setup that includes the React Compiler, then adjusts its rule set before analysis begins.
From there, the important work happens in parallel. Oxlint handles the rule-based diagnostics, Knip looks for dead code and unused dependencies, and the results are merged, filtered against local config, and fed into the scoring logic. Errors count more than warnings, so the number reflects severity, not just volume.
That is why the score feels more like triage than a tally sheet. A codebase can have a lot of noise and still be usable, while a smaller set of severe issues can drag the health number down fast.
Why the `.ami/skills` folder matters
The most surprising part of the repo is not the scanner. It is the skills layer. react-doctor can detect agent environments, then offer a path that packages its React rules for tools like Cursor and Claude Code.
That is the key shift. Traditional linting tells a human what broke. react-doctor tries to teach the model what not to do next time, which is a much more interesting product bet if AI is now writing a large share of the first draft.
What it catches that a normal React lint stack misses
The real comparison is not react-doctor versus one linter. It is react-doctor versus the assembled stack most teams already maintain: ESLint, React plugins, dead-code tools, and a lot of human interpretation glued together by habit.
| Layer | react-doctor | ESLint plus plugins | Manual review |
|---|---|---|---|
| Output | A score plus prioritized diagnostics | A long list of independent warnings | Comments and intuition |
| Coverage | Oxlint rules plus Knip dead-code analysis | Depends on which plugins you wire up | Depends on reviewer memory |
| Framework awareness | Detects Next.js, React Native, and React Compiler patterns | Possible, but only if configured | Often inconsistent |
| Agent use | Ships `.ami/skills` for coding agents | No native skills layer | Not applicable |
| Best fit | Baseline, CI gate, agent guidance | Everyday linting | Final human judgment |
That table hides the most opinionated part of the repo. react-doctor is not only checking syntax or style. It is enforcing ideas like giant component thresholds, Next.js-specific rules, and framework boundaries that generic tooling often leaves as tribal knowledge.
Where the score helps, and where it can mislead
A single health score is useful because it gives teams a baseline they can track in CI, dashboards, and agent workflows. It is also dangerous for the same reason, because numbers can make messy judgment feel settled when it is not.
That is why the best use of react-doctor is as an initial filter, not a final referee. An engineer writing about it on a real Next.js app noted that the findings were useful, but that merging too many fixes at once could create regressions. That sounds right. Automate the scan, then apply human pacing to the fixes.
