aislop

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, hidden fallbacks, 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 10 language targets (TypeScript, JavaScript, Expo / React Native, Python, Go, Rust, Ruby, PHP, C#, C/C++). 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@latest scan

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

Also available on npm, Yarn, Bun, Homebrew, and PyPI:

npm install -g aislop                # npm
yarn dlx aislop scan                 # Yarn (no install)
bun add -g aislop                    # Bun
brew install scanaislop/tap/aislop   # Homebrew
pipx install aislop                  # Python

See Installation for every option.

Language support

aislop supports TypeScript, JavaScript, Expo / React Native, Python, Go, Rust, Ruby, PHP, C#, and C/C++.

Coverage includes formatting, linting, complexity, AI-slop detection, and security checks. Some checks use optional system tools; see Installation and the rules reference for details.

aislop agent                 # repair with your coding agent (Codex/Claude/OpenCode)
aislop fix                   # auto-fix the mechanical issues
aislop fix -f                # aggressive fixes (deps, unused files)
aislop ci                    # CI mode (JSON + gate)
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@latest badge to auto-generate. Free at scanaislop.com.

See it in action

Scan

Installation

The same CLI is published to npm, Homebrew, and PyPI. Pick whichever fits your stack.

Node / npm

# Run without installing
npx aislop@latest scan

# npm
npm install --save-dev aislop

# yarn
yarn add --dev aislop

# pnpm
pnpm add -D aislop

# bun
bun add -d aislop

# Global
npm install -g aislop

Also available as @scanaislop/aislop on GitHub Packages.

Package installation does not run dependency lifecycle scripts. After installing, run aislop-tools once if you want bundled Ruff and golangci-lint coverage; the core scanner works without it.

Homebrew (macOS / Linux)

brew install scanaislop/tap/aislop

Homebrew installs Node.js as a dependency if it isn't already present. Details: homebrew-tap.

Python / pipx

pipx install aislop

pipx keeps aislop in its own isolated environment. Needs Node.js on PATH. Details: PyPI package.

Full reference for every channel, optional bundled tooling, and external tools: docs/installation.md.

Usage

Examples below use the installed aislop binary. For a one-off latest run, prefix the command with npx aislop@latest, for example npx aislop@latest scan.

Command reference

aislop --help              # clean overview
aislop commands            # every public command and major flag
aislop <command> --help    # detailed help for one command
aislop version             # installed version
aislop -V                  # installed version
aislop update              # current and latest npm versions

Scan

aislop scan                       # current directory
aislop scan ./src                 # specific directory
aislop scan --changes             # changed files from HEAD
aislop scan --changes --base origin/main  # changed vs a base branch (PRs)
aislop scan --staged              # staged files only
aislop scan -d                    # verbose file/rule detail
aislop scan --json                # JSON output
aislop scan --sarif               # SARIF 2.1.0 output (GitHub code scanning)
aislop scan --format json         # alternate JSON form
aislop scan --include "src/**"    # only matching paths
aislop scan --exclude "dist,gen"  # skip extra paths

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: aislop scan --exclude "**/*.test.ts,dist"

Unsupported languages: aislop only analyses the 10 language targets above. If a repo is mostly something else (Swift, Kotlin, Java, …), 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/hidden-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

The deterministic layer beneath aislop agent: auto-fix what's purely mechanical (formatters, unused imports, dead code). For anything that needs judgement, reach for aislop agent or hand off to your coding agent with full diagnostic info.

aislop fix                 # auto-fixes
aislop fix --dry-run       # preview planned steps without writing files
aislop fix --changes       # only rewrite files changed vs HEAD
aislop fix --staged        # only rewrite staged files
aislop fix -d              # detailed fix progress
aislop fix --safe          # only reversible fixes (imports, comment removal, safe formatters)
aislop fix -f              # aggressive: deps, unused files
aislop fix -p              # print an agent handoff prompt

--safe restricts the run to fixes that cannot change behaviour — unused-import removal, import merging, narrative-comment removal, and formatter runs that do not execute project-controlled configuration. Anything that deletes code, rewrites behaviour/attributes, or can load executable formatter