Installation

CLI only (no config required)

Run astro-doctor without installing it at all:

pnpm dlx @santi020k/astro-doctor@latest

npx @santi020k/astro-doctor@latest

yarn dlx @santi020k/astro-doctor@latest

bunx @santi020k/astro-doctor@latest

This scans the current directory and prints a health report with score.

Install as a dev dependency

Add to your project so it's always available and pinned to a version:

pnpm add -D @santi020k/astro-doctor

npm install --save-dev @santi020k/astro-doctor

yarn add -D @santi020k/astro-doctor

bun add -D @santi020k/astro-doctor

VS Code Extension (Editor Integration)

For the best experience in VS Code or Cursor, install the official Astro Doctor extension from theMarketplace:

ext install santi020k.vscode-astro-doctor

This provides live diagnostics, hovers, quick fixes, and a visual health score sidebar. SeeVS Code Extension for full features.

ESLint plugin (Standalone or alternative editor integration)

For live in-editor diagnostics (VS Code, Neovim, WebStorm, etc.), install the ESLint plugin and add it to your flat config:

pnpm add -D @santi020k/eslint-plugin-astro-doctor astro-eslint-parser

npm install --save-dev @santi020k/eslint-plugin-astro-doctor astro-eslint-parser

yarn add -D @santi020k/eslint-plugin-astro-doctor astro-eslint-parser

bun add -D @santi020k/eslint-plugin-astro-doctor astro-eslint-parser

// eslint.config.js
import astroDoctorPlugin from '@santi020k/eslint-plugin-astro-doctor'

export default [
  astroDoctorPlugin.configs.recommended,
  // Add your other config here
]

The recommended config includes astro-eslint-parser as the parser for*.astro files and enables all rules at their default severities.

Agent skills

To install the AI agent skills into your project (so Claude, Cursor, and Copilot Workspace know the rules and how to fix them):

astro-doctor install

This copies three skill files to .agents/skills/ in your project root.

GitHub Action

See GitHub Action for full setup instructions. No extra installation is required — the action runs astro-doctor internally.

Works alongside eslint-plugin-astro

astro-doctor is designed to complementeslint-plugin-astro(the official community plugin), not replace it. The two cover different ground:

If you already use eslint-plugin-astro (e.g. viaeslint-config-basic), add astro-doctor on top for performance scanning, health scoring, and AI context.