AI-powered code linter with custom YAML rules. Write your rules in plain English, pick an AI model, and let it review your code. Works with Gemini, Claude, GPT and more via OpenRouter, or run locally with Ollama.
AI coding assistants are awesome — but they make mistakes. They shove business logic into route handlers, leak stack traces to users, create god functions, or forget parameterized queries. Traditional linters can't catch these because they don't understand intent.
ai-lint lets you control AI with AI. Write the rules that matter to your codebase in plain English, and let a language model enforce them on every commit. It catches exactly the kind of "smart but sloppy" mistakes that slip through code review.
The rules are especially powerful when generated with tools like Claude Code or similar AI coding assistants. Describe what you want to enforce, let the AI draft the rule — done. When you run into false positives (e.g. a FAQ page that legitimately mentions error messages), just tweak the exclude pattern or make the prompt more specific. The feedback loop is fast because rules are just YAML and natural language.
npm i -g @handmade-systems/ai-lintOr clone and build locally:
git clone https://github.com/handmade-systems/ai-lint.git
cd ai-lint
npm install && npm run build
npm link # makes ai-lint available globally- Node.js 20+
- An OpenRouter API key or a local Ollama installation
- A git repo (for
--changedmode and.gitignorefiltering)
ai-lint uses OpenRouter as API gateway — one key, all models.
- Create an account at openrouter.ai
- Grab an API key from Keys
- Set it:
export OPEN_ROUTER_KEY=sk-or-v1-...Or drop a .env file in your project root:
OPEN_ROUTER_KEY=sk-or-v1-...
Run models entirely on your machine — no API key, no cloud, no cost (besides your own hardware).
- Install Ollama
- Pull a model:
ollama pull llama3.2 # 3B params, fast
ollama pull qwen2.5:14b # 14B params, better quality- Set your
.ai-lint.ymlto use Ollama:
provider: ollama
model: qwen2.5:14b
# provider_url: http://localhost:11434/v1 # default, change if needed
rules:
- id: no_secrets
name: "No hardcoded secrets"
severity: error
glob: "src/**/*.ts"
prompt: |
Check for hardcoded secrets, API keys, passwords, or tokens.No OPEN_ROUTER_KEY needed — Ollama runs locally. Any model available via ollama list can be used.
1. Create a .ai-lint.yml in your project root:
model: gemini-flash # cheapest and fastest
concurrency: 5
git_base: main
rules:
- id: no_logic_in_routes
name: "No business logic in route handlers"
severity: error
glob: "src/routes/**/*.ts"
prompt: |
Check if this route handler contains business logic.
Route handlers should only: parse the request, call a service/use-case,
and return a response. Any validation, data transformation,
database queries, or business rules should live in a service layer.
- id: no_direct_db_in_components
name: "React components must not access the database"
severity: error
glob: "src/components/**/*.tsx"
prompt: |
Check if this React component imports or calls database clients
directly (e.g. prisma, drizzle, knex, mongoose, pool.query).
Data fetching belongs in server actions, API routes, or
dedicated data-access layers — not in component code.
- id: error_messages_no_internals
name: "Don't leak internals in error messages"
severity: error
glob: "src/**/*.ts"
exclude: "src/**/*.test.ts"
prompt: |
Check if error messages returned to the client expose internal
details like stack traces, table names, file paths, SQL queries,
or service URLs. User-facing errors should be generic.
Internal details belong in server-side logs only.2. Add these to your .gitignore:
# ai-lint cache (auto-generated)
.ai-lint/
# API keys
.env3. Run it:
# Lint everything
ai-lint lint --all
# Only git-changed files (compared to main)
ai-lint lint --changed
# Specific files
ai-lint lint src/foo.ts src/bar.ts
# Verbose mode — shows API vs cache per check
ai-lint lint --all --verbose
# Report-only mode for tool/agent integrations
ai-lint lint --all --report-only --report-file .ai-lint/report.json4. Generate rules interactively:
ai-lint generate-rule
# > Ensure all API endpoints validate request bodies with zodThe best way to create rules is with an AI coding assistant like Claude Code:
- Describe the problem: "We keep getting PRs where route handlers contain database queries directly"
- Let the AI draft the rule — it generates the YAML with id, glob pattern, and prompt
- Test it:
ai-lint lint --all - Refine on false positives: If
src/pages/faq.tsxgets flagged incorrectly, add anexcludepattern or make the prompt more specific (e.g. "Ignore files that only contain static content")
No AST visitors, no plugin APIs, no compilation step — just YAML and natural language. 🎯
ai-lint lint [files...]
--all Lint all files matching rule globs
--changed Lint only git-changed files (vs git_base)
--base <branch> Override git_base branch
--config <path> Config file (default: .ai-lint.yml)
--verbose Show API vs cache per check
--report-only Suppress normal lint output and write JSON report
--report-file JSON report path (default: .ai-lint/report.json)
Exit codes: 0 = all passed, 1 = errors found, 2 = config/runtime error
When --report-only is enabled:
- Normal lint output is suppressed
- A JSON report is written to
--report-file - CLI prints a single final line:
Report written: <absolute-path>
Report payload:
{
"mode": "report-only",
"generated_at": "2026-02-12T18:00:00.000Z",
"exit_code": 0,
"summary": {},
"results": [],
"error": null
}Check your config file without running any lints.
ai-lint validate
--config <path> Config file (default: .ai-lint.yml)
Interactively generate a new rule with AI. Describe what to check, get YAML back, confirm to append. Creates the config file if it doesn't exist yet.
ai-lint generate-rule
--config <path> Config file (default: .ai-lint.yml)
Delete the result cache.
Show cache statistics (entries, size on disk).
Config file: .ai-lint.yml (validated against a JSON schema)
| Field | Type | Default | Description |
|---|---|---|---|
provider |
"openrouter" | "ollama" |
"openrouter" |
AI provider |
provider_url |
string |
"http://localhost:11434/v1" |
Provider URL (Ollama only) |
model |
string |
"gemini-flash" |
AI model — OpenRouter shortname or any Ollama model name |
concurrency |
1-20 |
5 |
Max parallel API calls |
git_base |
string |
"main" |
Base branch for --changed |
rules |
array |
(required) | Your lint rules |
When
provider: ollama, themodelfield is required and accepts any model name fromollama list(e.g.llama3.2,qwen2.5:14b,codellama:13b). Whenprovider: openrouter(default), use one of the shortnames below.
| Model | OpenRouter ID | Cost (in/out per 1M tokens) | Best for |
|---|---|---|---|
gemini-flash |
google/gemini-2.5-flash |
$0.15 / $0.60 | Default — fast, cheap, solid 🏃 |
haiku |
anthropic/claude-haiku-4.5 |
$1.00 / $5.00 | Higher quality, 10x pricier |
sonnet |
anthropic/claude-sonnet-4.5 |
$3.00 / $15.00 | Best quality for tricky rules |
opus |
anthropic/claude-opus-4.6 |
$15.00 / $75.00 | Overkill, but available 🤷 |
| Field | Type | Required | Description |
|---|---|---|---|
id |
string |
yes | Unique ID (snake_case) |
name |
string |
yes | Human-readable name |
severity |
"error" | "warning" |
yes | Severity level |
glob |
string |
yes | File matching pattern |
exclude |
string |
no | Files to skip |
prompt |
string |
yes | What to check (natural language) |
model |
string |
no | Override model for this rule |
- Config — loads
.ai-lint.yml, validates against JSON schema - Files — resolves via
--all(glob),--changed(git diff), or explicit paths; respects.gitignore - Matching — finds rules whose
globmatches andexcludedoesn't - Cache — skips API calls if (file hash + prompt hash) is already cached
- AI — sends each (file, rule) pair to the AI model via OpenRouter or Ollama
- Report — groups violations by file, prints to console
Results are cached in .ai-lint/cache.json based on SHA-256 hashes of file content and rule prompt. Cache auto-invalidates when either changes. Force a fresh run with ai-lint cache clear.
These are the kinds of checks that traditional linters simply can't do — architectural and semantic rules that require understanding intent.
- id: no_logic_in_routes
name: "No business logic in route handlers"
severity: error
glob: "src/routes/**/*.ts"
prompt: |
Check if this route handler contains business logic.
Route handlers should only: parse the request, call a service,
and return a response. Anything else belongs in a service layer.
- id: no_direct_db_in_components
name: "React components must not access the database"
severity: error
glob: "src/components/**/*.tsx"
prompt: |
Check if this React component imports or calls database clients
directly. Data fetching belongs in server actions, API routes,
or data-access layers — not in component code.- id: error_messages_no_internals
name: "Don't leak internals in error messages"
severity: error
glob: "src/**/*.ts"
exclude: "src/**/*.test.ts"
prompt: |
Check if error messages returned to the client expose internal
details like stack traces, table names, file paths, SQL queries,
or service URLs. User-facing errors should be generic.
- id: no_secrets_in_code
name: "No hardcoded secrets"
severity: error
glob: "src/**/*.{ts,tsx}"
prompt: |
Check for hardcoded secrets, API keys, passwords, tokens, or
connection strings. Environment variables via process.env are fine.- id: no_god_functions
name: "Functions shouldn't be god functions"
severity: warning
glob: "src/**/*.ts"
exclude: "src/**/*.test.ts"
prompt: |
Check if any function is excessively complex: more than 4 nesting
levels, more than 5 early returns, mixed concerns, or 60+ lines.
Suggest splitting if found.
- id: no_raw_sql_strings
name: "Use parameterized queries"
severity: error
glob: "src/**/*.ts"
prompt: |
Check if SQL queries are built by concatenating or interpolating
strings. Use parameterized queries or a query builder instead.
Template literals with ${} inside SQL are a red flag.npm run build # Build with tsup
npm run check # Biome lint + format check
npm test # Unit tests
npm run test:coverage # Tests with coverage report
npm run dev # Run CLI via tsxSee CONTRIBUTING.md for setup, code style, and PR guidelines.
MIT