GitHub - scanaislop/aislop: Catch the slop AI coding agents leave in your code. 40+ rules, 7 languages, sub-second, deterministic, no LLM. MIT.

Catch the slop AI coding agents leave in your code.

The patterns Claude Code, Cursor, Codex, and OpenCode leave behind: narrative comments above self-explanatory code, swallowed exceptions, as any casts, hallucinated imports, duplicated helpers, dead code, todo stubs, oversized functions. Tests pass. Lint passes. The code rots anyway.

aislop catches them. 40+ rules across 7 languages (TS/JS, Python, Go, Rust, Ruby, PHP, Java). Scores every change 0–100. Sub-second. Deterministic — no LLM in the runtime path, same code in, same score out. MIT-licensed, free CLI.

Quick start

No install needed. Works on any project. Get your score in seconds.

npx aislop fix                   # auto-fix issues
npx aislop fix -f                # aggressive fixes (deps, unused files)
npx aislop ci                    # CI mode (JSON + gate)
npx aislop hook install --claude # per-edit hook

Public badge: Show your score on your README

[![aislop](https://badges.scanaislop.com/score/<owner>/<repo>.svg)](https://scanaislop.com)

Run npx aislop badge to auto-generate. Free at scanaislop.com.

See it in action

Scan

Installation

# Run without installing
npx aislop scan

# npm
npm install --save-dev aislop

# yarn
yarn add --dev aislop

# pnpm
pnpm add -D aislop

# Global
npm install -g aislop

Also available as @scanaislop/aislop on GitHub Packages.

Usage

Scan

npx aislop scan           # current directory
npx aislop scan ./src     # specific directory
npx aislop scan --changes # changed files from HEAD
npx aislop scan --staged  # staged files only
npx aislop scan --json    # JSON output

Exclude files: node_modules, .git, dist, build, coverage excluded by default. Add more in .aislop/config.yml:

exclude:
  - "**/*.test.ts"
  - src/generated

Or via CLI: npx aislop scan --exclude "**/*.test.ts,dist"

Extend config: Project config can extend a parent:

# .aislop/config.yml
extends: ../../.aislop/base.yml
ci:
  failBelow: 80             # override specific keys

Fix

Auto-fix what's mechanical (formatters, unused imports, dead code). For issues that need context, hand off to your agent with full diagnostic info.

npx aislop fix                 # safe auto-fixes
npx aislop fix -f              # aggressive: deps, unused files

Hand off to agent

When auto-fix can't solve it, pass the remaining issues to your coding agent with full context:

npx aislop fix --claude        # Claude Code
npx aislop fix --cursor        # Cursor (copies to clipboard)
npx aislop fix --gemini        # Gemini CLI
npx aislop fix --codex         # Codex CLI
# Also: --windsurf, --amp, --aider, --goose, --opencode, --warp, --kimi, --antigravity, --deep-agents, --vscode
npx aislop fix --prompt        # print prompt (agent-agnostic)

Install hook

Runs after every agent edit. Feedback flows back immediately.

npx aislop hook install --claude           # Claude Code
npx aislop hook install --cursor           # Cursor
npx aislop hook install --gemini           # Gemini CLI
npx aislop hook install                    # all supported agents
npx aislop hook install claude cursor      # specific agents

Runtime adapters (scan + feedback): claude, cursor, gemini.
Rules-only (agent reads rules): codex, windsurf, cline, kilocode, antigravity, copilot.

Quality-gate mode: Blocks if score regresses below baseline.

npx aislop hook install --claude --quality-gate
npx aislop hook baseline                    # re-capture baseline
npx aislop hook status                      # list installed
npx aislop hook uninstall --claude          # remove

Docs: /docs/hooks

MCP server

Expose aislop as MCP tools for Claude Desktop, Cursor, Codex:

Tools: aislop_scan, aislop_fix, aislop_why, aislop_baseline

CI

npx aislop ci                  # JSON output, exits 1 if score < threshold

Other commands

npx aislop init                # create .aislop/config.yml
npx aislop init --strict       # enterprise-grade gate: all engines, typecheck, failBelow 85
npx aislop rules               # list rules
npx aislop badge               # print badge URL
npx aislop                     # interactive menu

Docs: commands

CI integration

Pre-commit

GitHub Actions

Run npx aislop init and accept the workflow prompt, or add manually:

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: 20
- run: npx aislop@latest ci .

Composite action:

- uses: actions/checkout@v4
- uses: scanaislop/aislop@v0.8

Quality gate

Set minimum score in .aislop/config.yml:

aislop ci exits 1 when score < threshold. Docs: CI/CD

For teams

scanaislop is the hosted platform for teams:

PR gates with score thresholds
Standards hierarchy (org → team → project)
Dashboards and agent attribution
Visual rules manager

Same engines, same scores. CLI is MIT-licensed. Learn more →

Why aislop

AI coding tools generate code that compiles and passes tests but ships with patterns no engineer would write. aislop gives you one score, one gate, and auto-fixes what it can.

One score: 0-100, enforced in CI. Weighted so sloppy patterns hit harder than style noise.
Auto-fix first: Clears formatters, unused imports, dead code mechanically. Hands off the rest to your agent with full context.
Deterministic: Regex + AST + standard tooling. No LLMs, no API calls. Same code in, same score out.
Zero-config start: npx aislop scan works on any repo. Add .aislop/config.yml to tune.

What it catches

Six deterministic engines run in parallel:

Engine	What it checks	How
Formatting	Code style consistency	Biome, ruff, gofmt, cargo fmt, rubocop, php-cs-fixer
Linting	Language-specific issues	oxlint, ruff, golangci-lint, clippy, expo-doctor
Code Quality	Complexity and dead code	Function/file size limits, deep nesting, unused files/deps (knip), AST-based unused-declaration removal
AI Slop	AI-authored code patterns	Narrative comments, trivial comments, dead patterns, unused imports, `as any`, `console.log` leftovers, TODO stubs, generic names
Security	Vulnerabilities and risky code	eval, innerHTML, SQL/shell injection, dependency audits (npm/pip/cargo/govulncheck)
Architecture	Structural rules (opt-in)	Custom import bans, layering rules, required patterns

See the full rules reference.

Docs

Installation · Commands · Rules · Config · Scoring · CI/CD · Telemetry

Community

Discussions for questions, rule requests, and false-positive triage · Issues for bugs

Contributing

See CONTRIBUTING.md. AI assistants: AGENTS.md.

Acknowledgments

Built on: Biome, oxlint, knip, ruff, golangci-lint, expo-doctor

Contributors

Auto-updated by .github/workflows/contributors.yml. Link commit email or add to .github/contributors-overrides.json.

License

MIT