npx check-ai

Audit any repository for AI-readiness.

One command. 66 checks. Zero dependencies. Scans for agent configs, repo hygiene, grounding docs, testing safety nets, prompt templates, MCP integrations, AI dependencies — and scores it all on a 0–10 scale.

🧹 Repo Hygiene  ████████████░░░  77% (26/34)
  📄 Grounding Docs ██████████░░░░░  65% (15/23)
  🧪 Testing       ██████████████░  90% (9/10)
  🤖 Agent Configs  ████████████░░░  75% (55/73)
  🔒 AI Context    ██████░░░░░░░░░  40% (6/15)
  🧩 Prompts       ████░░░░░░░░░░░  28% (5/18)
  🔌 MCP           ███████████████  100% (11/11)
  📦 AI Deps       ███████████████  100% (4/4)

  ──────────────────────────────────────────────────

   A   Strong — AI-ready

  ████████████████████████████████░░░░░░░░  7.8/10
  38 of 66 checks passed · 131/188 pts

  ──────────────────────────────────────────────────

Install & Run

npx check-ai

Scan a specific repo:

npx check-ai /path/to/repo

Options

Flag	Description
--json	Machine-readable JSON output
--verbose, -v	Include low-priority (nice-to-have) recommendations
--no-interactive	Disable animated output (auto-detected in CI / pipes)
--ci	Alias for --no-interactive
-h, --help	Show help
--version	Show version

CI Integration

check-ai exits with code 1 when the score is below 3/10, so you can use it as a CI gate:

# GitHub Actions
- name: AI Readiness Check
  run: npx check-ai

# GitLab CI
ai-audit:
  script: npx check-ai --ci

JSON Output

Pipe results into other tools or dashboards:

npx check-ai --json | jq '.score'

{
  "score": 7.8,
  "grade": "A",
  "label": "Strong — AI-ready",
  "checks": { "passed": 38, "total": 66 },
  "sections": { ... },
  "findings": [ ... ]
}

---

What It Audits

check-ai runs 66 checks grouped into 8 sections. Each check has a weight based on real-world impact.

🧹 Repo Hygiene

A clean, well-structured repo is the foundation for AI agents to work effectively.

Check	What it looks for
Git repo	.git directory
Gitignore	.gitignore
Env example	.env.example, .env.sample, .env.template
Editor config	.editorconfig
Linter	ESLint, Pylint, Ruff, RuboCop, golangci-lint configs
Formatter	Prettier, Biome, deno fmt, clang-format, rustfmt configs
CI pipeline	GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis, Bitbucket Pipelines
Standard scripts	start, test, lint in package.json or Makefile
Dev container	.devcontainer/ for reproducible environments

📄 Grounding Docs

Documentation that helps AI agents understand what your project is and how it works.

Check	What it looks for
README	README.md
README quality	Checks for install instructions, usage, structure, code blocks, headings
Contributing guide	CONTRIBUTING.md
Architecture doc	architecture.md, ARCHITECTURE.md, docs/architecture.md
Tech stack doc	tech-stack.md, docs/tech-stack.md
AI requirements	.ai/requirements, .ai/docs, docs/prd
llms.txt	llms.txt, llms-full.txt (the llms.txt standard)

🧪 Testing Safety Net

Tests catch agent-introduced regressions before they ship.

Check	What it looks for
Test directory	tests/, test/, __tests__/, spec/, e2e/, cypress/, playwright/
Test runner config	Jest, Vitest, Playwright, Cypress, pytest, RSpec configs
Coverage config	nyc, c8, coveragerc, Codecov configs

🤖 Agent Configs

The core of AI-readiness. Having at least one AI tool configured earns a large bonus — because in practice, teams use one tool (Cursor or Windsurf or Claude Code), not all of them at once.

Check	What it looks for
At least one AI tool	Any tool-specific config found (big bonus)
AGENTS.md	Universal cross-tool agent instructions (agents.md)
AGENTS.md quality	Content analysis: build commands, test instructions, style guide, code examples
Nested AGENTS.md	Deep scan for per-module AGENTS.md files
.agents/	Agent assets directory (skills, plans)
Claude Code	CLAUDE.md, .claude/, .claude/settings.json
Cursor	.cursorrules, .cursor/rules/
Windsurf	.windsurfrules (legacy), .windsurf/rules/ (new), .windsurf/skills/, .windsurf/workflows/
GitHub Copilot	.github/copilot-instructions.md, .github/instructions/
OpenAI Codex	.codex/, CODEX.md
Google Gemini	.gemini/
Aider	.aider.conf.yml
Roo Code	.roo/
Continue	.continue/, .continuerc.json
Amp (Sourcegraph)	Reads AGENTS.md (counted via AGENTS.md check)
JetBrains Junie	.junie/, .junie/guidelines.md
Entire HQ	.entire/ (captures AI agent sessions per git push)
OpenCode	opencode.json, .opencode/ (agents, commands, skills, plugins)
Zed	.rules
Trae	.trae/rules/
Cline	.clinerules

🔒 AI Context

Files that control what AI agents can and cannot see.

Check	What it looks for
Cursor ignore	.cursorignore
Cursor indexing ignore	.cursorindexingignore
AI ignore	.aiignore, .aiexclude
CodeRabbit	.coderabbit.yaml
Copilot ignore	.copilotignore
Codeium ignore	.codeiumignore
Instruction files	Deep scan for .instructions.md files

🧩 Prompts & Skills

Reusable prompt templates and agent skill definitions.

Check	What it looks for
Prompt templates (.yml)	Deep scan for .prompt.yml files
Prompt templates (.md)	Deep scan for .prompt.md files
Prompts directory	prompts/, .prompts/, .ai/prompts/
Skills	Deep scan for SKILL.md files
Claude commands	.claude/commands/

🔌 MCP (Model Context Protocol)

Tool integrations that extend agent capabilities.

Check	What it looks for
MCP config	.mcp.json, mcp.json
MCP server count	Parses config and counts configured servers
MCP directory	.mcp/

📦 AI Dependencies

Detects AI SDK usage in your project.

Check	What it looks for
AI SDKs	Scans package.json, requirements.txt, pyproject.toml for OpenAI, Anthropic, LangChain, Vercel AI SDK, Google AI, Hugging Face, MCP SDK, vector DBs, tokenizers, and more (~40 packages)

---

How Scoring Works

Each check has a weight based on how much it impacts AI-readiness.

The raw score is normalized to a 0–10 scale:

Grade	Score	Verdict
A+	9–10	Exemplary — fully AI-ready
A	7–9	Strong — AI-ready
B	5–7	Decent — partially AI-ready
C	3–5	Weak — minimal AI setup
D	1–3	Poor — barely AI-aware
F	0–1	None — not AI-ready

Scoring Philosophy

• Having any one AI tool configured earns a big bonus. People use Cursor or Windsurf or Claude Code — not all at once. The tool doesn't penalize you for picking one.
• AGENTS.md is weighted highest among individual checks because it's the universal, cross-tool standard.
• Content quality matters, not just file existence. AGENTS.md and README.md are analyzed for real signals like build commands, test instructions, code examples, and headings.
• Deep scanning walks your file tree (up to 6 levels) to find nested AGENTS.md, .prompt.yml, SKILL.md, and .instructions.md files.

---

Interactive Mode

When run in a terminal (TTY), check-ai shows:

• Spinner with live progress during scanning
• Animated score bar that fills in real-time
• Section-by-section reveal with staggered items

Automatically falls back to static output when piped or in CI environments.

---

Zero Dependencies

Built entirely with Node.js built-ins (fs, path, readline). No install required beyond npx. Works offline — no network calls, pure static analysis.

License

MIT