# React Doctor

Diagnose React codebase health. Scans for security, performance, correctness, and architecture issues, then outputs a 0–100 score with actionable diagnostics.

Note: dead-code detection was removed in v0.2 (previously powered by knip). For dead-code analysis, run `npx knip` directly.

## Usage

Run this at your project root:

```bash
npx react-doctor@latest
```

Use `--verbose` to see affected files and line numbers:

```bash
npx react-doctor@latest --verbose
```

Use `--diff [base]` to scan only files changed vs a base branch (default: auto-detected `main`/`master`). On the default branch, scans uncommitted working-tree changes; on a feature branch, scans changes vs the base.

```bash
npx react-doctor@latest --verbose --diff
```

Use `--score` to output only the numeric score:

```bash
npx react-doctor@latest --score
```

Use `--json` for a single structured JSON report (suppresses other output):

```bash
npx react-doctor@latest --json | jq '.summary'
```

Use `-y` to skip prompts (required for non-interactive environments like CI or coding agents):

```bash
npx react-doctor@latest -y
```

Use `--staged` for pre-commit hooks (scans only staged files):

```bash
npx react-doctor@latest --staged
```

Use `--annotations` to emit GitHub Actions annotations:

```bash
npx react-doctor@latest --annotations
```

Use `--fail-on <level>` to control exit codes (`error`, `warning`, `none`):

```bash
npx react-doctor@latest --fail-on error
```

Use `--offline` to skip the score API and the share URL. Offline runs print no score; the rest of the report renders normally:

```bash
npx react-doctor@latest --offline
```

Install the skill into your coding agent (50+ agents supported via agent-install: Claude Code, Codex, Cursor, Factory Droid, Gemini CLI, GitHub Copilot, Goose, OpenCode, Pi, Windsurf, Roo Code, Cline, Kilo Code, Warp, Replit, OpenHands, Continue, and more):

```bash
npx react-doctor@latest install
```

## Options

```
Usage: react-doctor [directory] [options]

Options:
  -v, --version      display the version number
  --lint             enable linting (default: on)
  --no-lint          skip linting
  --verbose          show file details per rule
  --score            output only the score
  --json             output a single structured JSON report (suppresses other output)
  -y, --yes          skip prompts, scan all workspace projects
  --full             skip prompts, always run a full scan (decline diff-only)
  --project <name>   select workspace project (comma-separated for multiple)
  --diff [base]      scan only files changed vs base branch or uncommitted changes
  --offline          skip the score API and share URL (no score is shown)
  --staged           scan only staged (git index) files for pre-commit hooks
  --fail-on <level>  exit with error code on diagnostics: error, warning, none
  --annotations      output diagnostics as GitHub Actions annotations
  -h, --help         display help for command
```
