aislop

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 11 language targets (TypeScript, JavaScript, Expo / React Native, Python, Go, Rust, Ruby, PHP, Java, 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

1. Scan. Get your score in seconds. No install needed, works on any project.

npx aislop@latest scan

2. Install the hook so your coding agent fixes slop before it lands, on every edit. The hook calls aislop directly, so install the CLI first.

npm install -g aislop && aislop hook install

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

npm install -g aislop                # npm
yarn dlx aislop scan                 # Yarn (no install)
bunx aislop scan                     # Bun (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, Java, 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
bunx aislop@latest scan   # Bun

# 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
aislop scan --share               # print a public report link and badge

Share: --share reads the origin remote and, for a GitHub repo, prints the public report link https://scanaislop.com/<owner>/<repo> and the README badge markdown. The report works for public repos only. Anyone with the link can see the score for the default branch. Nothing is uploaded and no network call is made; the page scans the public repo itself.

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 11 language targets above. If a repo is mostly something else (Swift, Kotlin, Scala, …), 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 (or a bare aislop-ignore) 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. A misspelled directive such as aislop-ignore-nextline suppresses nothing and is reported as ai-slop/unknown-directive.

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 configuration (console/dead-code removal, lint autofixes, Ruby/PHP formatter config, unused-declaration and dependency pruning) is skipped, so a --safe run is genuinely "apply and commit".

Run a local repair agent

aislop agent keeps the deterministic scanner in charge while using the coding agent you already have installed. It creates a local git worktree, runs safe fixes, streams a headless Codex / Claude Code / OpenCode / Pi repair session, verifies the result with aislop scan --json, writes a local session transcript, and leaves the diff for review.

aislop agent providers        # see installed providers and setup hints
aislop agent connect codex    # run the provider's own local login flow
aislop agent use codex        # save a repo-local default provider
aislop agent use auto         # clear the default and auto-detect
aislop agent plan             # preview provider, worktree, findings, PR/apply behavior
aislop agent monitor          # stream scans when local git changes settle
aislop agent monitor --background
aislop agent monitor list     # list background monitors
aislop agent monitor stop     # stop the latest background monitor
aislop agent monitor --repair --in-place
aislop agent                  # auto-pick an installed provider
aislop agent --provider codex # switch provider
aislop agent --background     # run locally in the background
aislop agent --apply          # apply verified diff back to this repo
aislop agent --pr             # commit, push, and open a draft PR
aislop agent sessions         # list recent local repair sessions
aislop agent show             # show the latest session timeline and summary
aislop agent apply            # apply a reviewed worktree session later
aislop agent watch            # stream the latest session transcript
aislop agent stop             # stop the latest running background session

No OpenAI or Anthropic API key is requested by aislop; provider CLIs use their own existing local auth. A saved provider default lives in .aislop/agent/provider.json and is kept out of commits through the repo's local Git exclude. Session transcripts live under .aislop/agent/sessions/, and agent sessions/worktrees are also excluded locally. Provider JSONL is normalized in the terminal stream while raw lines stay in the transcript.

Hand off to agent

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

aislop fix --claude        # Claude Code
aislop fix --codex         # Codex CLI
aislop fix --cursor        # Cursor (copies to clipboard)
aislop fix --gemini        # Gemini CLI
aislop fix --prompt        # print prompt (agent-agnostic)

Other fix handoff flags: --windsurf, --vscode, --amp, --antigravity, --deep-agents, --kimi, --opencode, --warp, --aider, --goose, --pi, --crush.

Install hook

Runs after every agent edit. Feedback flows back immediately.

aislop hook install --claude           # Claude Code
aislop hook install --cursor           # Cursor
aislop hook install --gemini           # Gemini CLI
aislop hook install --pi               # pi
aislop hook install                    # pick agents interactively
aislop hook install claude cursor      # specific agents
aislop hook install --agent claude,pi  # comma-separated agents
aislop install claude cursor           # alias for hook install
aislop install hooks --claude          # natural alias for hook install

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

Hook install flags: --agent <names>, -g, --global, --project, --dry-run, --yes, --quality-gate, plus per-agent shortcuts --claude, --cursor, --gemini, --pi, --codex, --windsurf, --cline, --kilocode, --antigravity, --copilot.

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

aislop hook install --claude --quality-gate
aislop hook baseline                    # re-capture baseline
aislop hook status                      # list installed
aislop hook uninstall --claude          # remove
aislop uninstall claude                  # alias for hook uninstall
aislop uninstall hooks --claude          # natural alias for hook uninstall

Docs: /docs/hooks

MCP server

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

// ~/.cursor/mcp.json or Claude Desktop config
{
  "mcpServers": {
    "aislop": {
      "command": "npx",
      "args": ["-y", "aislop-mcp"]
    }
  }
}

Tools: aislop_scan, aislop_fix, aislop_why, aislop_baseline

CI

aislop ci                  # JSON output, exits 1 if score < threshold
aislop ci --changes --base origin/main  # gate only the files a PR changes
aislop ci --human          # human-friendly CI output
aislop ci --sarif          # SARIF output for code scanning
aislop baseline write      # accept current findings; ci then fails only on new ones
aislop baseline prune      # drop baseline entries for findings you fixed

Set ci.baseline: .aislop/ci-baseline.json after aislop baseline write so scan and ci use it. See docs/ci.md.

ci accepts the same --changes / --staged / --base <ref> scoping as scan. Use --changes --base origin/<target> to gate a pull request on only the files it touches; the score gate and exit code still apply.

Other commands

aislop                         # interactive menu
aislop init                    # create .aislop/config.yml
aislop init --strict           # enterprise-grade gate: all engines, typecheck, failBelow 85
aislop doctor                  # check which engines can run here
aislop rules                   # list rules with severity, fixability, and score impact
aislop rules --search          # searchable rule explorer
aislop badge                   # print badge URL
aislop badge --owner o --repo r --json
aislop trend                   # show score history over time
aislop trends                  # alias for trend
aislop trend --limit 20
aislop update                  # show current and latest npm versions
aislop upgrade                 # alias for update
aislop commands                # full command list

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 and aislop trends read it and print a relative-time 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:

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: v1
    hooks:
      - id: aislop

GitHub Actions

Run aislop init and accept the workflow prompt, or add manually. The self-contained form always runs the latest CLI, so there's nothing to bump:

name: aislop

on:
  pull_request:
  push:
    branches: [main]

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npx --yes aislop@latest ci

Prefer the Marketplace Action? @v1 runs the latest release. From v0.18.1, pinning a release tag such as @v0.18.1 (or its commit SHA) runs the matching CLI version, so Dependabot's github-actions updates keep it current. Older tags run the latest CLI unless version is set.

- uses: actions/checkout@v4
- uses: scanaislop/[email protected]

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

Bitbucket Pipelines

Bitbucket clones shallow by default, so fetch the PR target branch and gate on only the changed files with ci --changes --base:

# bitbucket-pipelines.yml
pipelines:
  pull-requests:
    "**":
      - step:
          name: aislop gate
          image: node:24
          clone:
            depth: full   # branch diffs need history
          script:
            - git fetch origin "$BITBUCKET_PR_DESTINATION_BRANCH"
            - npx --yes aislop@latest ci --changes --base FETCH_HEAD

ci applies the score gate and exit code, so no JSON parsing or hand-rolled threshold is needed. More providers: CI/CD.

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@latest 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, google-java-format, dotnet format, clang-format
Linting	Language-specific issues	oxlint, ruff, golangci-lint, clippy, expo-doctor, PMD, Checkstyle, Roslynator, JetBrains InspectCode, cppcheck, clang-tidy
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, unsafe deserialization, dependency audits for JavaScript, Python, Rust, Go, and .NET
Architecture	Structural rules (opt-in)	Custom import bans, layering rules, required patterns

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

Docs on the website (preferred for search and agents): start · commands · rules · configure · scoring · CI · hooks

In this repo: Installation · Commands · Rules · Config · Scoring · CI/CD · Telemetry · Research program

Community

Discord for community chat and support · 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

• @daveslutzkin
• @gtheys
• @heavykenny
• @mtschoen
• @myke-awoniran
• @swjturay
• @yashrajoria

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

License

MIT