> ## Documentation Index
> Fetch the complete documentation index at: https://scanaislop-update.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Get started with aislop in under a minute
> Scan your first project, read your score, repair issues, and add a CI quality gate — all in four steps with no upfront configuration.
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.
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.
```bash theme={null}
npx aislop@latest scan
```
You can also scan a specific directory:
```bash theme={null}
npx aislop@latest scan ./src
```
Or scope the scan to only the files you've changed:
```bash theme={null}
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](/installation) for every package manager option.
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:
```bash theme={null}
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:
```ts theme={null}
// 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.
After installing aislop (see [Installation](/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.
```bash theme={null}
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:
```bash theme={null}
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:
```bash theme={null}
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:
```bash theme={null}
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
```
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.
```bash theme={null}
aislop ci
```
For pull requests, gate only the files the PR changes:
```bash theme={null}
aislop ci --changes --base origin/main
```
Set your minimum score threshold in `.aislop/config.yml` (create it with `aislop init`):
```yaml theme={null}
ci:
failBelow: 70
```
The fastest way to add aislop to **GitHub Actions** — no version to maintain:
```yaml theme={null}
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:
```yaml theme={null}
- 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/` 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:
```bash theme={null}
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:
```bash theme={null}
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.
All install channels: npm, Yarn, pnpm, Bun, Homebrew, pipx, and GitHub Packages.
Run Codex, Claude Code, or OpenCode while aislop owns scoring and verification.
Every flag, output format, path scoping option, and config key for `aislop scan`.
Browse all 50+ rules by engine, language, and severity.
Tune thresholds, override rule severity, and set up project-wide ignore patterns.