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. 50+ rules across 7 languages (TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP). 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

[![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
npx aislop scan --sarif   # SARIF 2.1.0 output (GitHub code scanning)

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"

Unsupported languages: aislop only analyses the 8 languages above. If a repo is mostly something else (C, C++, C#, Swift, Kotlin, …), scoring a handful of incidental files would misrepresent it, so aislop withholds the score and says so rather than printing a number off code it never read. --json returns score: null, scoreable: false, and a coverage breakdown.

Per-rule severity: Override the severity of any rule by id, or turn it off:

# .aislop/config.yml
rules:
  ai-slop/narrative-comment: warning   # error | warning | off
  ai-slop/trivial-comment: "off"       # drop this rule entirely
  security/hardcoded-secret: error

off drops matching diagnostics; error/warning rewrites severity before scoring and reporting. Absent map keeps default behavior.

Suppress findings inline: Silence a specific line when you know better, with an optional reason after --:

// aislop-ignore-next-line ai-slop/empty-fallback -- options is validated upstream
const opts = { ...defaults, ...(input || {}) };

const legacy = doThing(); // aislop-ignore-line

aislop-ignore-next-line covers the line below, aislop-ignore-line the line it sits on, and aislop-ignore-file (place anywhere in the file) the whole file. Name one or more rules to scope the suppression, or omit them to silence every rule on that line. The directive works in any comment syntax (//, #, <!-- -->). Suppressed findings are removed before scoring, and the run reports how many were silenced.

Ignore whole paths: Add an .aislopignore at the project root (same glob semantics as exclude, # comments allowed):

src/generated
**/*.snap
legacy

Extend config: Project config can extend a parent:

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

Editor validation: Point your editor at the JSON Schema in schema/aislop.config.schema.json for autocomplete and validation of .aislop/config.yml. Regenerate it from the source config schema with pnpm gen:schema.

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                 # auto-fixes
npx aislop fix --safe          # only reversible fixes (imports, comment removal, formatting)
npx aislop fix -f              # aggressive: deps, unused files

--safe restricts the run to fixes that cannot change behaviour — unused-import removal, import merging, narrative-comment removal, and formatting. Anything that deletes code or rewrites behaviour/attributes (console/dead-code removal, lint autofixes, unused-declaration and dependency pruning) is skipped, so a --safe run is genuinely "apply and commit".

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, --pi, --crush, --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 --pi               # pi
npx aislop hook install                    # all supported agents
npx aislop hook install claude cursor      # specific agents

Runtime adapters (scan + feedback): claude, cursor, gemini, pi.
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 trend               # show score history over time
npx aislop                     # interactive menu

Score history: a normal (full-project, interactive) scan appends a compact record to .aislop/history.jsonl (timestamp, score, error/warning counts, file count, CLI version). aislop trend reads it and prints a table plus an ASCII sparkline of recent scores. History is a local side effect only: it is never written for --json/--sarif output, in CI, or when AISLOP_NO_HISTORY=1 is set, so machine output stays clean.

Docs: commands

CI integration

Pre-commit

Run directly on staged files:

npx aislop scan --staged

Or wire it into the pre-commit framework via the bundled hook:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/scanaislop/aislop
    rev: v0.10.2
    hooks:
      - id: aislop

GitHub Actions

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

name: aislop

on:
  pull_request:
  push:
    branches: [main]

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: scanaislop/aislop@v0.10.2
        with:
          version: latest

uses: scanaislop/aislop@v0.10.2 pins the GitHub Action wrapper. version: latest follows the latest npm CLI. For fully deterministic CI, set both to the same release:

- uses: actions/checkout@v4

- uses: scanaislop/aislop@v0.10.2
  with:
    version: "0.10.2"

Manual workflow without the Marketplace Action:

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

GitHub code scanning (SARIF): emit a SARIF 2.1.0 report and upload it so findings appear in the Security tab:

- run: npx aislop@latest scan . --sarif > aislop.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: aislop.sarif

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:

See the full rules reference.

Research

aislop rules are shaped by public scans and benchmark-derived failure modes, not only local fixtures. The research program defines how to run repeatable open-source scans: pin the cohort, store raw JSON, classify findings, fix noisy rules with regression tests, and publish the limits.

Docs

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

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