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

# skip files via glob

$ npx aislop scan --exclude "**/*.test.ts"

# comma-separated list

$ npx aislop scan --exclude node_modules,dist,logs

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

Exclude files and directories

Defaults cover node_modules, .git, dist, build, coverage. Add more in .aislop/config.yml:

exclude:
  - "**/*.test.ts"
  - src/generated
  - legacy

Or override per-run with --exclude (comma-separated or repeatable). Priority: CLI > config > defaults. Patterns use micromatch glob syntax.

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 --yes aislop@latest ci

# human output, still exits non-zero

$ npx --yes aislop@latest 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.

hook new in 0.6.0

Wire aislop into the agent's native hook lifecycle so findings flow back on every edit, not just at handoff. Supports Claude Code (PostToolUse), Cursor (afterFileEdit), Gemini CLI (AfterTool), plus rules-only installers for Codex, Windsurf, Cline, Kilo Code, Antigravity, and Copilot.

# single agent

$ npx aislop hook install --claude

# all supported agents

$ npx aislop hook install

# block Claude on regression

$ npx aislop hook install --claude --quality-gate

# list installed hooks

$ npx aislop hook status

# exact removal, sentinel-verified

$ npx aislop hook uninstall

Every install is idempotent (SHA-256 hash fence), every uninstall is exact. Details, feedback contract, and baseline flow: Agent hooks.

Strict team bootstrap

Teams rolling out agents under a strict engineering standard can skip the wizard and write a hardened starting point: all engines enabled, architecture rules scaffolded, typecheck on, CI gate at 85, and a GitHub Actions workflow included.

$ npx aislop init --strict

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.