AI Guard

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

Website  •  npm Package  •  GitHub Repository  •  Rules Catalog  •  Documentation

---

What is AI Guard?

AI Guard (eslint-plugin-ai-guard) is a deterministic ESLint plugin, CLI, and GitHub Action 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)"}
        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 three 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

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

---

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 deterministically verifies the output in CI

This dual-layer defense minimizes review friction and ensures generated code meets your security standard on the first pass.

---

GitHub Action

The official AI Guard GitHub Action runs on PRs, detects changed files, provides step summaries, outputs SARIF 2.1.0, and posts inline PR annotations directly on GitHub:

# .github/workflows/ai-guard.yml
name: AI Guard

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  ai-guard-scan:
    name: AI Guard Code Review
    runs-on: ubuntu-latest

    permissions:
      contents: read
      security-events: write
      actions: read

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Required for git diff comparison

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Run AI Guard
        uses: ai-guard-dev/eslint-plugin-ai-guard@v1
        with:
          preset: 'recommended'
          fail-on: 'high'
          changed-only: 'true'
          upload-sarif: 'true'

Action Inputs (action.yml)

Action Outputs

---

SARIF & GitHub Code Scanning

AI Guard natively outputs SARIF 2.1.0 (Static Analysis Results Interchange Format). When uploaded via the GitHub Action or github/codeql-action/upload-sarif@v3, findings integrate directly with GitHub Advanced Security:

• Inline PR Annotations: Direct comments on the exact source lines where flaws exist.
• Security Dashboard: Persistent alerts under your repository's Security → Code scanning tab.
• Merge Protection: Block merges automatically when high-confidence security or async bugs are detected.

Visual Previews

Inline Pull Request Annotations

GitHub Advanced Security Summary

Persistent Code Scanning Dashboard

---

Rule Examples (Before & After)

1. no-floating-promise (Unhandled Promises)

// ❌ BAD: Floating promise. Errors are dropped silently.
async function syncUserProfile(user: User) {
  sendTelemetryEvent('user_sync', user.id);
  database.save(user);
}

// ✅ GOOD: Awaited, explicitly handled, or marked with void
async function syncUserProfile(user: User) {
  await database.save(user);
  void sendTelemetryEvent('user_sync', user.id); // Explicitly unhandled
}

2. no-hardcoded-secret (Committed Credentials)

// ❌ BAD: Secret committed inline
const client = new PaymentGateway({
  apiKey: 'sk-prod-983427598273498273948273',
});

// ✅ GOOD: Read from environment variable (Autofixable!)
const client = new PaymentGateway({
  apiKey: process.env.API_KEY,
});

3. no-await-in-loop (Sequential Latency Trap)

// ❌ BAD: Consecutive awaits block each iteration sequentially
async function fetchAllUsers(ids: string[]) {
  const users = [];
  for (const id of ids) {
    users.push(await fetchUser(id));
  }
  return users;
}

// ✅ GOOD: Concurrently fetched with Promise.all (Autofixable!)
async function fetchAllUsers(ids: string[]) {
  return await Promise.all(ids.map((id) => fetchUser(id)));
}

4. no-empty-catch (Swallowed Errors)

// ❌ BAD: Exception swallowed without trace
try {
  parseConfiguration(rawConfig);
} catch (e) {}

// ✅ GOOD: Logged, rethrown, or documented (Autofixable!)
try {
  parseConfiguration(rawConfig);
} catch (e) {
  logger.error('Configuration parsing failed', { error: e });
  throw e;
}

5. no-sql-string-concat (SQL Injection)

// ❌ BAD: Dynamic string interpolation in SQL
const query = `SELECT * FROM users WHERE organization_id = '${orgId}' AND role = '${role}'`;
await db.query(query);

// ✅ GOOD: Parameterized query binding
const query = 'SELECT * FROM users WHERE organization_id = $1 AND role = $2';
await db.query(query, [orgId, role]);

---

Automatic Remediation (Autofix)

Rules that have deterministic solutions provide automatic autofix handlers. Run ESLint's native --fix flag to automatically resolve them:

npx eslint . --fix

---

Performance & Philosophy

• Zero LLM Overhead: AI Guard does not call external APIs, does not incur token costs, and does not add LLM latency. A scan of 100+ files executes in milliseconds.
• 100% Deterministic: Every finding is derived strictly from Abstract Syntax Tree analysis. No probabilistic drift, no non-deterministic hallucinated findings.
• Low False Positives: Built with precision-first design. Context-sensitive rules are configured at warn or off in the recommended preset so developers are never blocked by noise.
• Self-Scanning: AI Guard enforces its own rules on its own codebase in CI using the strict preset.

---

Learn More & Ecosystem

Visit getaiguard.dev to explore interactive documentation, rule catalogs, benchmarks, and deep-dive engineering articles.

Official Links

• Website: https://getaiguard.dev
• GitHub Organization: https://github.com/ai-guard-dev
• Repository: https://github.com/ai-guard-dev/eslint-plugin-ai-guard
• npm Registry: https://www.npmjs.com/package/eslint-plugin-ai-guard
• GitHub Action: ai-guard-dev/eslint-plugin-ai-guard@v1

---

Contributing

We welcome contributions, new rule ideas, bug reports, and false-positive reports!

1. Check out our Contributing Guide for local setup and testing standards.
2. Review our Security Policy to report vulnerabilities responsibly.
3. Check open issues or submit new ones on our Issue Tracker.

---

License

MIT © AI Guard Authors. Free and open source forever.