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

npx aislop scan

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

[](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

npx aislop scan --staged

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:

ci: failBelow: 70

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

• @heavykenny
• @myke-awoniran
• @yashrajoria

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

License

MIT