Using with Coding Agents

Integrate React Doctor with Cursor, Claude, OpenCode, and other AI coding assistants

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

This command works with:

• 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:

1. Learns React best practices - Understands all React Doctor rules
2. Runs checks automatically - Scans code after making changes
3. Suggests fixes - Recommends solutions based on diagnostics
4. Validates improvements - Re-runs scans to verify fixes worked

Agent Workflow

Coding agents use React Doctor in a verify-fix-verify loop:

1. Make changes

   Agent modifies your React code (new feature, bug fix, refactor)

2. Run scan

   Agent executes npx react-doctor . --verbose --diff to check changes

3. Review diagnostics

   Agent reads errors and warnings, prioritizes critical issues

4. Apply fixes

   Agent resolves issues one by one, starting with errors

5. 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

The agent will parse the output and suggest fixes based on diagnostics.

Automated Environment Detection

React Doctor automatically detects when it’s running inside a coding agent by checking environment variables:

• CLAUDECODE - Claude Code
• CURSOR_AGENT - Cursor Agent
• OPENCODE - OpenCode
• CODEX_CI - Codex
• AMP_HOME - Amp Code
• AMI - 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

This is much faster than full scans and focuses on your changes.

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

Each diagnostic includes:

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.

Coding agents load this skill automatically and follow the workflow defined.

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+):

node --version

See Troubleshooting for Node.js version issues.

Example: OpenCode Integration

Here’s how OpenCode uses React Doctor:

1. User requests feature

   “Add a login form with email validation”

2. OpenCode writes code

   Creates components, hooks, and validation logic

3. OpenCode runs React Doctor

   npx react-doctor . --verbose --diff

4. OpenCode reviews diagnostics

   Finds issues like missing error boundaries, accessibility problems

5. OpenCode applies fixes

   Wraps form in ErrorBoundary, adds ARIA labels, fixes hooks

6. OpenCode verifies

   Re-runs scan, confirms score improved from 72 → 84

The entire process happens automatically without manual intervention.

Coding agents work best with React Doctor when you let them run checks after every significant change.