React Doctor has built-in support for coding agents, teaching them React best practices and automatically running health checks.
Installation for Agents
Install React Doctor as a skill for your coding agent:
curl -fsSL https://react.doctor/install-skill.sh | bash
- Cursor (Cursor Agent)
- Claude Code (Anthropic)
- OpenCode (open-source)
- Amp Code
- Codex
- Gemini CLI
- Windsurf
- Antigravity
The skill teaches agents about 47+ React best practice rules so they avoid common issues while coding.
What the Skill Does
After installation, your coding agent:
- Learns React best practices - Understands all React Doctor rules
- Runs checks automatically - Scans code after making changes
- Suggests fixes - Recommends solutions based on diagnostics
- Validates improvements - Re-runs scans to verify fixes worked
Agent Workflow
Coding agents use React Doctor in a verify-fix-verify loop:
Make changes
Agent modifies your React code (new feature, bug fix, refactor)
Run scan
Agent executes npx react-doctor . --verbose --diff to check changes
Review diagnostics
Agent reads errors and warnings, prioritizes critical issues
Apply fixes
Agent resolves issues one by one, starting with errors
Verify improvements
Agent re-runs React Doctor to confirm the score improved
Agents automatically use --diff mode to scan only changed files, making checks fast even in large codebases.
Manual Agent Commands
You can also ask your coding agent to run React Doctor manually:
Full Scan
npx -y react-doctor@latest . --verbose
Scan Only Changes
npx -y react-doctor@latest . --verbose --diff
Get Score Only
npx -y react-doctor@latest . --score
Automated Environment Detection
React Doctor automatically detects when it’s running inside a coding agent by checking environment variables:
CLAUDECODE - Claude CodeCURSOR_AGENT - Cursor AgentOPENCODE - OpenCodeCODEX_CI - CodexAMP_HOME - Amp CodeAMI - Ami
When detected, React Doctor:
- Skips interactive prompts (runs non-interactively)
- Outputs machine-readable diagnostics
- Suggests appropriate fixes for the agent to apply
You don’t need to configure anything. React Doctor automatically adjusts its behavior when running in agent environments.
Best Practices for Agents
1. Run After Each Change
Agents should run React Doctor after completing a feature or fix:
// Agent pseudocode
async function completeTask() {
await makeCodeChanges();
const result = await exec('npx react-doctor . --diff');
if (result.hasErrors) {
await applyFixes(result.diagnostics);
await exec('npx react-doctor . --diff'); // Verify
}
}
2. Use Diff Mode for Speed
Always use --diff to scan only changed files:
npx react-doctor . --verbose --diff
3. Fix Errors Before Warnings
Agents should prioritize errors (severity: “error”) over warnings:
const errors = diagnostics.filter(d => d.severity === 'error');
const warnings = diagnostics.filter(d => d.severity === 'warning');
// Fix errors first
for (const error of errors) {
await fixIssue(error);
}
4. Verify Score Improvements
After fixes, re-run to confirm the score increased:
npx react-doctor . --score
If the score doesn’t improve after fixes, the agent may have introduced new issues. Re-run with --verbose to debug.
Using the Node.js API
Agents can use the programmatic API instead of CLI:
import { diagnose } from "react-doctor/api";
const result = await diagnose("./path/to/react-project", {
lint: true,
deadCode: true,
});
console.log(result.score); // { score: 82, label: "Good" }
console.log(result.diagnostics); // Array of issues
interface Diagnostic {
filePath: string;
plugin: string;
rule: string;
severity: "error" | "warning";
message: string;
help: string;
line: number;
column: number;
category: string;
}
Skill Configuration
The React Doctor skill is defined at skills/react-doctor/SKILL.md:
---
name: react-doctor
description: Run after making React changes to catch issues early
version: 1.0.0
---
Scans your React codebase for security, performance, correctness,
and architecture issues.
Troubleshooting Agent Integration
Skill Not Found
If the agent doesn’t recognize React Doctor:
# Re-install the skill
curl -fsSL https://react.doctor/install-skill.sh | bash
Agent Times Out
For large codebases, use --diff mode or specify a project:
npx react-doctor . --project my-app --diff
Agent Skips Checks
Ensure Node.js version is compatible (v20.19.0+ or v22.12.0+):
See Troubleshooting for Node.js version issues.
Example: OpenCode Integration
Here’s how OpenCode uses React Doctor:
User requests feature
“Add a login form with email validation”
OpenCode writes code
Creates components, hooks, and validation logic
OpenCode runs React Doctor
npx react-doctor . --verbose --diff
OpenCode reviews diagnostics
Finds issues like missing error boundaries, accessibility problems
OpenCode applies fixes
Wraps form in ErrorBoundary, adds ARIA labels, fixes hooks
OpenCode verifies
Re-runs scan, confirms score improved from 72 → 84
Coding agents work best with React Doctor when you let them run checks after every significant change.