What is eslint-plugin-ai-guardrails?

An ESLint plugin that enforces structure-first linting rules designed to catch the code quality patterns AI coding assistants (Copilot, Cursor, ChatGPT, Claude) introduce most often — including god files, god functions, orphan TODOs, and redundant comments.

Does it support ESLint v9 flat config?

Yes. Use aiGuardrails.flatConfigs.recommended in your eslint.config.mjs for ESLint v9. ESLint v8 legacy .eslintrc config is also supported via plugin:ai-guardrails/recommended.

Is it free and open source?

Yes. MIT license. Free forever. Source code on GitHub, package on npm.

Which file types does it lint?

TypeScript files only: .ts, .tsx, .mts, and .cts. JavaScript files are intentionally excluded — this plugin targets TypeScript-first AI-assisted workflows.

How do I fail the CI build on any warning?

Add --max-warnings 0 to your lint script: "lint": "eslint . --max-warnings 0". Then gate your build: "build": "npm run lint && npm run typecheck && ".

eslint-plugin-
ai-guardrails

Stop AI-generated code from becoming long-term tech debt. Enforce structure-first linting rules that catch the patterns AI coding tools get wrong most often.

Works with Copilot, Cursor, ChatGPT, Claude, and any AI coding assistant. Supports ESLint v8 & v9, TypeScript ≥ 5.

Read the Docs →View on GitHub View on npm

Quick install

npm install --save-dev eslint-plugin-ai-guardrails

Why AI Guardrails?

Catch What AI Gets Wrong

AI coding assistants are incredibly productive — but they introduce predictable quality drift. These aren't style nitpicks; they're the exact patterns that turn a productive AI sprint into months of refactoring.

No More God Files

max-file-lines

Problem AI keeps appending to one file instead of splitting

Fix Warns when a file exceeds 300 lines

No More God Functions

max-function-lines

Problem AI generates monolithic functions with everything inlined

Fix Warns when a function exceeds 50 lines

No Orphan TODOs

no-orphan-todos

Problem AI leaves TODO / FIXME / HACK with no tracking reference

Fix Errors without a link or deadline

No Redundant Comments

no-ai-obvious-comments

Problem AI adds massive blocks of unnecessary explanations

Fix Enforces max density (20%), length, and quality

Quick Start

Get Started in Seconds

One command sets up everything — ESLint config, scripts, and TypeScript baseline.

One-command setup recommended

npx eslint-plugin-ai-guardrails init

Or add to your ESLint v9 flat config manually

eslint.config.mjs

// eslint.config.mjs
import aiGuardrails from 'eslint-plugin-ai-guardrails';

export default [
  aiGuardrails.flatConfigs.recommended
];

Full installation guide in the docs →

Rules

Rules at a Glance

Rule	Default	Description
max-file-lines	warn	Prevent files from exceeding 300 lines
max-function-lines	warn	Prevent functions from exceeding 50 lines
no-orphan-todos	error	Require TODO/FIXME/HACK to include a tracking reference
no-ai-obvious-comments	warn	Enforce strict comment density, length, and quality constraints