https://github.com/f/check-ai
Audit any repository for AI-readiness.
https://github.com/f/check-ai
agents ai-readiness
Last synced: 3 months ago
JSON representation
Audit any repository for AI-readiness.
- Host: GitHub
- URL: https://github.com/f/check-ai
- Owner: f
- License: mit
- Created: 2026-02-16T10:56:54.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-16T13:13:48.000Z (4 months ago)
- Last Synced: 2026-02-16T20:08:37.653Z (4 months ago)
- Topics: agents, ai-readiness
- Language: JavaScript
- Homepage:
- Size: 111 KB
- Stars: 24
- Watchers: 0
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
npx check-ai
Audit any repository for AI-readiness.
[](https://github.com/f/check-ai)
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
```bash
npx check-ai
```
Scan a specific repo:
```bash
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:
```yaml
# GitHub Actions
- name: AI Readiness Check
run: npx check-ai
```
```yaml
# GitLab CI
ai-audit:
script: npx check-ai --ci
```
### JSON Output
Pipe results into other tools or dashboards:
```bash
npx check-ai --json | jq '.score'
```
```json
{
"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](https://llmstxt.org)) |
### 🧪 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](https://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