Get started with aislop in under a minute

You don’t need to install anything to get your first score. aislop runs directly from npx, works on any project regardless of language or framework, and produces a human-readable report with file locations and a 0-100 quality score. This guide takes you from zero to a gated repair workflow in four steps.

Run your first scan

From any project root, run aislop without installing it. The scan completes in sub-second time and produces a score plus a grouped list of findings.

npx aislop@latest scan

You can also scan a specific directory:

npx aislop@latest scan ./src

Or scope the scan to only the files you’ve changed:

npx aislop@latest scan --changes
npx aislop@latest scan --changes --base origin/main   # compare against a branch
npx aislop@latest scan --staged                       # staged files only

Once you’ve run npx aislop@latest scan once, add aislop as a dev dependency so you get the same version every time. See Installation for every package manager option.

Read your score and findings

aislop prints a 0–100 score, a per-engine breakdown, and a list of findings grouped by severity. Each finding includes the file path, line number, rule ID, and a short explanation.A typical output looks like this:

Score  74 / 100

✖  ai-slop/narrative-comment      src/auth/login.ts:14
   Remove comment that restates what the code already says.

✖  ai-slop/swallowed-exception   src/utils/parse.ts:88
   Exception is caught but not logged or re-thrown.

✖  security/eval                  src/sandbox.js:6
   Avoid eval() — use a safer alternative.

⚠  formatting/trailing-whitespace  src/index.ts:22

3 errors · 1 warning · 74/100

To get machine-readable output for scripting or CI tooling:

npx aislop@latest scan --json
npx aislop@latest scan --sarif    # SARIF 2.1.0 for GitHub code scanning

Suppressing a known false positive: if you know a specific finding is not a problem in your context, silence it inline with an optional reason:

// aislop-ignore-next-line ai-slop/narrative-comment -- required for API docs generation
// Returns the authenticated user or null if the session has expired.
export function getUser(): User | null { ... }

Use aislop-ignore-line for the current line, aislop-ignore-next-line for the line below, or aislop-ignore-file anywhere in a file to suppress all findings in that file. The same syntax works in any comment style (//, #, ). Suppressed findings are excluded from scoring and reported as a count at the end of the run.

Repair issues

After installing aislop (see Installation), use aislop agent for local repair sessions with Codex, Claude Code, or OpenCode. aislop creates an isolated worktree by default, runs safe mechanical fixes, streams the provider session, verifies the result, and leaves the diff for review.

aislop agent                 # auto-pick an installed provider
aislop agent providers       # see installed providers and setup hints
aislop agent connect codex   # run the provider's local login flow
aislop agent plan            # preview provider, worktree, findings, and apply behavior

Use aislop fix for deterministic mechanical cleanup:

aislop fix           # auto-fix all mechanical issues
aislop fix --safe    # only reversible fixes (imports, comments, formatting)
aislop fix -f        # aggressive: also prune unused deps and files

--safe restricts the run to fixes that cannot change behaviour. Use it when you want to apply and commit immediately without reviewing the diff.For legacy handoff flows, print or open a structured prompt with full diagnostic context:

aislop fix --claude    # Claude Code
aislop fix --cursor    # Cursor (copies prompt to clipboard)
aislop fix --codex     # Codex CLI
aislop fix --gemini    # Gemini CLI
aislop fix --prompt    # Print the prompt without opening an agent

Run aislop scan again after fixing to verify your score improved:

aislop scan

Recommended repair workflow for getting a project to 100/100:

aislop scan          # see all issues
aislop fix --safe    # apply only reversible fixes
aislop fix           # auto-fix formatting, lint, imports, comments
aislop agent plan    # preview the local repair session
aislop agent         # repair remaining issues with a local provider
aislop scan          # verify everything is resolved

Add to CI

Use aislop ci to enforce a minimum score on every push or pull request. It outputs JSON, applies your score gate, and exits with a non-zero code when the threshold is not met.

aislop ci

For pull requests, gate only the files the PR changes:

aislop ci --changes --base origin/main

Set your minimum score threshold in .aislop/config.yml (create it with aislop init):

ci:
  failBelow: 70

The fastest way to add aislop to GitHub Actions — no version to maintain:

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

Or use the Marketplace Action to pin a version for reproducible builds:

- uses: actions/checkout@v4
- uses: scanaislop/aislop@v1
  with:
    version: latest

aislop ci accepts the same --changes, --staged, and --base flags as aislop scan. Use --changes --base origin/<target> to limit the gate to only the files a pull request touches.

Install a per-edit hook so your coding agent sees the score after every change:

aislop hook install --claude    # Claude Code
aislop hook install --cursor    # Cursor
aislop hook install --gemini    # Gemini CLI

Add --quality-gate to block edits that regress the score below your baseline:

aislop hook install --claude --quality-gate

What’s next

You now have a scan, a score, a repair workflow, and a CI gate. Explore the rest of the docs to tune aislop for your project.

Installation

All install channels: npm, Yarn, pnpm, Bun, Homebrew, pipx, and GitHub Packages.

Local repair agent

Run Codex, Claude Code, or OpenCode while aislop owns scoring and verification.

Scan Command Reference

Every flag, output format, path scoping option, and config key for aislop scan.

Rules

Browse all 50+ rules by engine, language, and severity.

Configuration

Tune thresholds, override rule severity, and set up project-wide ignore patterns.

Get Started

Core Concepts

Get started with aislop in under a minute

What’s next

Installation

Local repair agent

Scan Command Reference

Rules

Configuration

​What’s next

Installation

Local repair agent

Scan Command Reference

Rules

Configuration

What’s next