Documentation

Commands.

Seven commands, each with a clear job. Most people only need three — scan, fix, ci — the rest are for setup and debugging.

The three you'll use every day

scan read-only

Runs every enabled engine, reports diagnostics, prints a 0–100 score. Never modifies files. Run this first on any new project to see what's there.

# current directory

$ npx aislop scan

# a subdirectory

$ npx aislop scan ./packages/api

# only files changed vs HEAD

$ npx aislop scan --changes

# only files staged for commit

$ npx aislop scan --staged

# machine-readable output

$ npx aislop scan --json

When to run: before you commit, to confirm the repo hasn't regressed. --staged is what you want inside a pre-commit hook.

fix modifies files

Applies the safe auto-fixes: formatters, unused imports, trivial and narrative comments, dead patterns, safe unused-var renames. Re-scans afterward so you see the final score.

# safe fixes only

$ npx aislop fix

# aggressive: unused deps/files, Expo

$ npx aislop fix -f

When to run: after a scan shows N fixable issues, or as part of a commit pipeline. -f is riskier (removes files, changes lockfile) — commit your work first.

ci exits non-zero below threshold

Same scan as scan, but outputs JSON by default and returns exit code 1 when the score drops below ci.failBelow in .aislop/config.yml, or when any error-severity diagnostic is present. Designed to be the gate in your workflow.

# JSON output, exit 1 on failure

$ npx aislop ci

# human output, still exits non-zero

$ npx aislop ci --human

When to run: as a GitHub Actions / GitLab CI / CircleCI step. Don't run it locally unless you want the JSON — use scan for interactive use.

Setup & debugging

init

Interactive wizard. Asks which engines to enable, your CI quality-gate threshold, whether to share anonymous usage stats, and whether to drop a GitHub Actions workflow. Writes .aislop/config.yml (always), .aislop/rules.yml (only if architecture engine is enabled), and .github/workflows/aislop.yml (if you say yes).

$ npx aislop init

When to run: once, on setup. Skip it if you're happy with defaults — aislop runs with zero config.

doctor

Checks which external tools are installed (Biome, oxlint, ruff, gofmt, cargo, rubocop, php-cs-fixer, pnpm, govulncheck, pip-audit, …) and reports what's missing. Tools that aren't installed are silently skipped during a scan — this tells you what you'd gain by installing them.

$ npx aislop doctor

When to run: if a scan shows fewer diagnostics than you'd expect, or an engine is marked skipped.

rules

Lists every detection rule aislop supports, grouped by engine. Each row shows the rule ID, whether it's auto-fixable, and a short description. Useful for grepping when you want to know where a specific diagnostic comes from.

$ npx aislop rules

fix --<agent>

After fix resolves what's safely fixable, the remaining issues need judgment (as any, oversized functions, complex refactors). These flags open your coding agent with a prompt containing the full diagnostic context.

$ npx aislop fix --claude

$ npx aislop fix --codex

$ npx aislop fix --cursor

# print the prompt instead of launching

$ npx aislop fix --prompt

Full list of 14 supported agents plus how the prompt is built: Agent handoff.

A typical day

First time in a new repo: npx aislop scan — see where you stand.
Clean up what's cheap: npx aislop fix — commit the result.
Set up the gate: npx aislop init — answer "yes" to the GitHub workflow prompt.
Commit .aislop/ and .github/workflows/aislop.yml. Push.
From now on: CI runs aislop ci on every PR and blocks below your threshold. You don't have to remember to run it.