AI Guard ESLint Plugin

AI Guard

Deterministic AST safety layer and CI guardrails for AI-assisted JavaScript and TypeScript code.

Website  •  npm Package  •  GitHub Repository  •  Rules Catalog  •  Benchmarks  •  Claude Code  •  Documentation

What is AI Guard?

AI Guard (eslint-plugin-ai-guard) provides:

• ESLint plugin with 18 deterministic rules and 4 presets (recommended, strict, security, agent)
• CLI (ai-guard) for terminal, changed-file, and CI scanning
• GitHub Action with native SARIF 2.1.0 output for GitHub Code Scanning
• Check integrity (ai-guard integrity) — detects changes that weaken checks: new suppressions, skipped or removed tests, lowered ESLint/TypeScript/coverage settings, removed CI steps
• Claude Code integration with hooks that send findings back to Claude and block finishing once when checks were weakened
• MCP server (ai-guard-mcp) for local AI-agent workflows over STDIO

It is engineered to detect reliability bugs, async hazards, security vulnerabilities, and code-scaffolding defects frequently introduced during AI-assisted development (GitHub Copilot, Cursor, Claude Code, Gemini Code Assist, etc.).

AI Guard analyzes Abstract Syntax Trees (AST) using ESLint's native engine. It runs locally in your editor, in your terminal via the zero-config CLI, and in your CI/CD pipelines via native SARIF 2.1.0 integration with GitHub Code Scanning.

What AI Guard is NOT

Important

• AI Guard is NOT an AI detector. It does not attempt to predict whether code was authored by an LLM or a human.
• AI Guard detects dangerous or fragile code patterns that LLMs repeatedly introduce due to incomplete context, hallucinated patterns, or probabilistic generation.
• AI Guard does NOT replace ESLint. It extends ESLint with 18 specialized, high-impact rules that core ESLint and standard configurations omit.

Why AI Guard?

AI coding assistants write code at remarkable velocity, but generated code repeatedly suffers from predictable reliability and security anti-patterns that conventional linters miss:

AI Guard provides an instantaneous, deterministic feedback loop that catches these issues before they reach pull requests or production.

Architecture & Workflow

flowchart TD
    subgraph Dev["1. Development & Prompt Phase"]
        A["Developer + AI Coding Assistant\n(Copilot, Cursor, Claude Code)"] --> B["JavaScript / TypeScript Code"]
    end

    subgraph ShiftLeft["Shift Left — Context Injection"]
        SL["npx ai-guard init-context"] -.-> CTX["CLAUDE.md\n.cursorrules\ncopilot-instructions.md"]
        CTX -.-> A
    end

    subgraph Analysis["2. Deterministic AST Analysis"]
        B --> C["ESLint Parser\n(espree / @typescript-eslint/parser)"]
        C --> D["AST Representation"]
        D --> E["AI Guard Rules Engine\n(18 Deterministic Rules)"]
    end

    subgraph Tiers["3. Classification & Presets"]
        E --> F{"Active Preset\n(recommended | strict | security | agent)"}
        F --> G["Confidence Tiering & AST Filtering"]
    end

    subgraph Outputs["4. Output & Remediation"]
        G --> H["Local CLI Scanning\n(ai-guard run / changed)"]
        G --> I["Autofix Remediation\n(eslint --fix)"]
        G --> J["HTML Dashboard\n(ai-guard report)"]
        G --> K["SARIF 2.1.0 Artifact\n(ai-guard --sarif)"]
    end

    subgraph CI["5. GitHub Pull Request & CI/CD"]
        K --> L["GitHub Action\nai-guard-dev/eslint-plugin-ai-guard@v1"]
        L --> M["GitHub Code Scanning Alerts"]
        L --> N["Inline PR Code Annotations"]
        L --> O["PR Status Check (Blocks Merge)"]
    end

Rules Catalog

AI Guard includes 18 deterministic rules divided into four specialized categories. Every rule is engineered with low false-positive heuristics and validated against real-world production codebases:

🔴 Security (6 Rules)

🟠 Reliability (4 Rules)

🟡 Async Stability (5 Rules)

🔵 AI Patterns (3 Rules)

* Enabled at error level in the strict preset.

Presets

AI Guard exports four official configurations ready for flat config or legacy setups:

Quick Start & Installation

Install the package as a development dependency using your package manager:

# npm
npm install --save-dev eslint-plugin-ai-guard

# pnpm
pnpm add -D eslint-plugin-ai-guard

# yarn
yarn add -D eslint-plugin-ai-guard

# bun
bun add -d eslint-plugin-ai-guard

Requirements

• Node.js: >= 20.0.0
• ESLint: >= 8.0.0 (Supports both Flat Config and legacy configs)
• TypeScript (optional): @typescript-eslint/parser >= 6.0.0 for TypeScript AST parsing

ESLint Configuration

1. Modern Flat Config (eslint.config.mjs / eslint.config.js)

AI Guard exports full native support for modern ESLint Flat Config:

// eslint.config.mjs
import aiGuard from 'eslint-plugin-ai-guard';

export default [
  {
    plugins: {
      'ai-guard': aiGuard,
    },
    rules: {
      ...aiGuard.configs.recommended.rules,
      // Custom overrides if desired:
      'ai-guard/no-floating-promise': 'error',
    },
  },
];

To use the strict or security preset in flat config:

// Strict preset — all 18 rules at error
rules: {
  ...aiGuard.configs.strict.rules,
}

// Security preset — security rules only
rules: {
  ...aiGuard.configs.security.rules,
}

2. Legacy Config (.eslintrc.js / .eslintrc.json)

// .eslintrc.js
module.exports = {
  plugins: ['ai-guard'],
  extends: ['plugin:ai-guard/recommended'],
};

CLI Reference

AI Guard includes a full-featured CLI binary (ai-guard) that runs out of the box with zero ESLint configuration files required:

npx ai-guard <command> [options]

Core Commands

run exit codes: 0 no errors · 1 errors found (or --max-warnings exceeded) · 2 scan did not run — the file passed to --path matches a built-in ignore pattern (node_modules/, dist/, build/, generated/, vendor/, …), so nothing was analyzed. Directory scans skip ignored files silently and never exit 2.

CLI Usage Examples

# 1. Immediate scan of current directory
npx ai-guard run

# 2. Strict CI scan failing only on high-confidence issues
npx ai-guard run --strict --fail-on high

# 3. Pull Request scan (diffs against PR target branch)
npx ai-guard changed --pr --sarif --sarif-output results.sarif

# 4. Generate AI agent guardrails for Cursor, Claude Code, and Copilot
npx ai-guard init-context --all

# 5. Generate interactive HTML diagnostic report
npx ai-guard report --output ai-guard-report.html

# 6. Save existing issues as baseline and only fail on new regressions
npx ai-guard baseline --save
npx ai-guard baseline --check

# 7. Fail a PR that skips tests, adds eslint-disable, or lowers coverage thresholds
npx ai-guard changed --pr --integrity enforce

Inline suppressions never hide findings silently

AI Guard reads eslint-disable directives itself; ESLint's own inline config is disabled in AI Guard's private ESLint instance, so a comment cannot make a finding vanish without a trace. --inline-suppressions selects the policy:

This applies to ai-guard run, changed, the GitHub Action, the Claude Code hook and MCP. It does not change how your own eslint . treats directives. TypeScript comments (@ts-ignore, @ts-nocheck) never affect AI Guard findings; ai-guard integrity reports newly added ones.

AI Agent Integration (init-context)

Standard linters only run after code has already been written. The init-context command shifts your guardrails left by embedding AI Guard's rules directly into the instruction files loaded by your AI coding tools:

npx ai-guard init-context --all

This generates three targeted context files:

1. CLAUDE.md — Automatically loaded by Claude Code
2. .cursorrules — Automatically loaded by Cursor
3. .github/copilot-instructions.md — Automatically loaded by GitHub Copilot

How Shift-Left Works

AI Guard (init-context)
       ↓
Generates project guardrail files (CLAUDE.md, .cursorrules, copilot-instructions.md)
       ↓
AI coding assistant reads safety rules before generating code
       ↓
Model avoids floating promises, empty catches, and hardcoded secrets at prompt time
       ↓
AI Guard CLI & GitHub Action determ