Documentation

From zero to quality gate in 60 seconds.

One command, one score. The aislop CLI scans your project, auto-fixes what's safe, and hands the rest to your agent. scanaislop is the platform that turns it into an org-wide engineering standard.

Quick Start

No config required. No account needed for local scans. Run this in any project:

# scan your project

$ npx aislop scan

# auto-fix what can be fixed safely

$ npx aislop fix

# CI mode (JSON output + quality gate)

$ npx aislop ci

Installation

Run without installing, or add to your project:

# run without installing

$ npx aislop scan

# npm

$ npm install --save-dev aislop

# pnpm

$ pnpm add -D aislop

# yarn

$ yarn add --dev aislop

# global

$ npm install -g aislop

Requires Node.js ≥ 20

Usage

Scan your project

$ aislop scan # scan current directory

$ aislop scan ./src # scan a specific directory

$ aislop scan --changes # only changed files from HEAD

$ aislop scan --staged # only staged files (pre-commit)

$ aislop scan --json # output JSON

Fix issues automatically

$ aislop fix # auto-fix formatting, imports, lint

$ aislop fix -f # aggressive: deps, unused files, Expo

Hand off to your agent

When auto-fix can't solve it, aislop generates a prompt with full context and opens your agent:

$ aislop fix --claude # Claude Code

$ aislop fix --codex # Codex CLI

$ aislop fix --cursor # Cursor

$ aislop fix --windsurf # Windsurf

$ aislop fix --gemini # Gemini CLI

$ aislop fix --amp # Amp

$ aislop fix --aider # Aider

$ aislop fix --goose # Goose

$ aislop fix --vscode # VS Code Copilot

$ aislop fix --prompt # print prompt for any agent

Other commands

$ aislop init # create .aislop/config.yml

$ aislop doctor # check available tools

$ aislop rules # list all built-in rules

$ aislop ci # CI mode with exit code

What it catches

Six deterministic engines run in parallel. No AI, no API calls, no network dependency. Every result is reproducible.

Engine	What it checks	How
Formatting	Code style consistency	Biome, ruff, gofmt, cargo fmt, rubocop
Linting	Language-specific issues	oxlint, ruff, golangci-lint, clippy
Code Quality	Complexity and dead code	Function/file size, nesting depth, knip
AI Slop	AI slop patterns	Trivial comments, swallowed exceptions, type abuse
Security	Vulnerabilities and secrets	eval, SQL injection, hardcoded secrets, dep audit
Architecture	Structural rules (opt-in)	Custom import bans, layering rules

Rules Reference

These rules run deterministically — no API calls, no AI inference, no network dependency. Every result is reproducible.

AI Slop Detection

Rule	Severity	What it catches
trivial-comment	warn	Comments restating code: "// Import React"
swallowed-exception	error	Empty catch blocks, catch that only logs
generic-naming	info	AI names: helper_1, data2, temp1
unused-import	warn	Imported symbols never used
console-leftover	warn	console.log/debug/info left in production
unsafe-type-assertion	warn	"as any" bypassing type safety
unreachable-code	warn	Code after return/throw statements
thin-wrapper	warn	Functions that only delegate to another
todo-stub	info	Unresolved TODO/FIXME/HACK/PLACEHOLDER
empty-function	info	Empty function bodies
constant-condition	warn	if (true), if (false), if (0)

Security

Rule	Severity	What it catches
hardcoded-secret	error	API keys, AWS creds, JWTs, DB URLs, passwords
eval	error	Use of eval() in JS/TS, Python, Ruby, PHP
sql-injection	error	Template literals / string concat in SQL queries
shell-injection	error	Template literals in command execution
innerHTML	error	.innerHTML assignment (XSS risk)
vulnerable-dependency	error	Known CVEs in npm/pip/cargo/go dependencies

Code Quality

Rule	Default	What it checks
function-too-long	> 80 LOC	Functions exceeding line count limit
file-too-large	> 400 LOC	Files exceeding line count limit
deep-nesting	> 5 levels	Nesting depth limit
too-many-params	> 6 params	Functions with excessive parameters
unused files	warn	Files not imported anywhere (knip)
unused dependencies	warn	Packages in package.json never imported

Configuration

aislop works with zero config. To customise, create .aislop/config.yml:

$ aislop init

# .aislop/config.yml

# This file becomes your team's engineering standard.

# Commit it to your repo. Every developer and every agent

# in your project is held to these rules.

ci:

failBelow: 70

engines:

format: true

lint: true

code-quality: true

ai-slop: true

security: true

architecture: false

complexity:

maxFunctionLines: 80

maxFileLines: 400

maxNestingDepth: 5

maxParams: 6

CI / CD

GitHub Actions

- uses: actions/setup-node@v6

with:

node-version: 20

- run: npm ci

- run: npx aislop ci

Pre-commit hook

$ npx aislop scan --staged

Quality gate

aislop ci exits with code 1 when the score drops below the threshold set in config. Use this with GitHub branch protection to block PRs that don't meet the bar.