Configure aislop with .aislop/config.yml - Scanaislop Documentation

Every aislop project is driven by a single YAML file at .aislop/config.yml. Run aislop init to generate one with sensible defaults, then edit only the keys you want to change — everything else falls back to the values documented here. The schema is versioned, so future breaking changes will bump version and old configs remain valid until you opt in.

Creating the config file

Run aislop init

Run the following command at the root of your project. aislop writes .aislop/config.yml and, if you accept the prompt, a GitHub Actions workflow.

aislop init

For a strict, enterprise-grade starting point with all engines on and a higher CI gate, use the --strict flag:

aislop init --strict

Review the generated file

Open .aislop/config.yml. Every top-level section is present with its default value. Sections you don’t touch need no changes.

Enable editor validation (optional)

Add a # yaml-language-server modeline at the top of the file to get autocomplete and inline validation in VS Code, JetBrains IDEs, and any editor with YAML Language Server support:

# yaml-language-server: $schema=https://scanaislop.com/schema/aislop.config.schema.json
version: 1
# ...

The canonical JSON Schema is published at https://scanaislop.com/schema/aislop.config.schema.json.

Full default config

The file below shows every key with its default value. You do not need to include keys you are not changing.

version: 1

engines:
  format: true
  lint: true
  code-quality: true
  ai-slop: true
  architecture: false    # opt-in, needs .aislop/rules.yml
  security: true

quality:
  maxFunctionLoc: 80
  maxFileLoc: 400
  maxNesting: 5
  maxParams: 6

lint:
  typecheck: false       # enable for TypeScript type-checking lint rules

security:
  audit: true
  auditTimeout: 25000

scoring:
  weights:
    format: 0.3
    lint: 0.6
    code-quality: 0.8
    ai-slop: 1.0
    architecture: 1.0
    security: 1.5
  thresholds:
    good: 75
    ok: 50
  smoothing: 20
  maxPerRule: 40

ci:
  failBelow: 70          # fail CI when score drops below this
  format: json

telemetry:
  enabled: true          # set to false to opt out

rules: {}                # per-rule severity overrides

exclude:
  - node_modules
  - .git
  - dist
  - build
  - coverage

include: []              # restrict scanning to these paths (empty = all)

Top-level sections

Each section controls a distinct part of the aislop run. You can add, remove, or override any section independently.

version

The config schema version. Always set this to 1. aislop rejects configs with an unknown version number so you get a clear error if a future release introduces a breaking change.

number

default:"1"

Config schema version. Must be 1.

engines

Boolean toggles that enable or disable each analysis engine. Disabling an engine removes it from the scan entirely — its findings neither appear in the report nor affect the score.

boolean

default:"true"

Formatting checks (Biome, ruff, gofmt, cargo fmt, rubocop, php-cs-fixer).

boolean

default:"true"

Language-specific linting (oxlint, ruff, golangci-lint, clippy, expo-doctor).

boolean

default:"true"

Complexity and dead code: function/file size, deep nesting, unused files and dependencies.

boolean

default:"true"

AI-authored pattern detection: narrative comments, swallowed exceptions, as any casts, TODO stubs, generic names, and more.

boolean

default:"false"

Custom import bans, layer enforcement, and required patterns. Requires .aislop/rules.yml. See Architecture Rules.

boolean

default:"true"

Secrets detection, risky constructs (eval, innerHTML, SQL injection), and dependency audits.

quality

Numeric thresholds that trigger code-quality warnings. See Engines → Quality thresholds for details.

number

default:"80"

Maximum lines of code per function.

number

default:"400"

Maximum lines of code per file.

number

default:"5"

Maximum control-flow nesting depth.

number

default:"6"

Maximum number of parameters per function.

lint

Options that apply to the lint engine only.

boolean

default:"false"

Enable TypeScript type-checking lint rules. Adds type-aware analysis but increases scan time. Recommended for TypeScript projects that want the strictest coverage.

security

Options that apply to the security engine only.

boolean

default:"true"

Run dependency audits (npm audit, pip-audit, cargo audit, govulncheck).

number

default:"25000"

Timeout in milliseconds for dependency audit commands. Increase this on slow networks or large dependency trees.

scoring

Controls how findings translate into the final 0–100 score.

object

A map of engine name to numeric multiplier. Higher values make that engine’s findings hurt the score more. See Engines → Scoring weights.

number

default:"75"

Scores at or above this value are labelled Healthy.

number

default:"50"

Scores at or above this value (but below good) are labelled Needs Work. Scores below this are Critical.

number

default:"20"

Reduces penalty spikes in large repos by dampening the logarithmic density curve. Increase for legacy codebases.

number

default:"40"

Caps the total weighted penalty any single rule family can contribute. Repeated findings still appear in the report, but one noisy rule cannot dominate the score.

Every native rule also has a score-impact tier. Strict defects and security findings score at full impact, maintainability findings score lower, and mechanical/style/advisory findings score softly. Run aislop rules to see each rule’s impact tier and rationale.

Settings used when you run aislop ci.

number

default:"70"

aislop ci exits with code 1 when the score is below this value. Set to 0 to disable the gate while still generating output.

string

default:"json"

Output format for aislop ci. Currently "json" is the only supported value.

telemetry

Controls anonymous usage telemetry.

boolean

default:"true"

Set to false to opt out of telemetry entirely. No data is sent when disabled.

rules

A map of rule ID to severity ("error", "warning", or "off"). Use this to tighten, loosen, or silence individual rules project-wide. See Rule Overrides for the full guide.

rules:
  ai-slop/narrative-comment: warning
  ai-slop/trivial-comment: "off"
  security/hardcoded-secret: error

exclude and include

string[]

Glob patterns for paths to skip during scanning. Replaces the default list entirely when specified — include defaults you want to keep.

string[]

default:"[]"

Restrict scanning to only these glob patterns. An empty array (the default) scans everything not excluded.

See Ignoring Code for all three ways to exclude paths.

extends

string | string[]

Path (or array of paths) to a parent config file to inherit from. See Config inheritance below.

Config inheritance

The extends: key lets a project inherit a parent config and override only the keys it cares about. This is the recommended pattern for monorepos or org-wide baselines.

Single parent

# packages/payments/.aislop/config.yml
extends: ../../.aislop/base.yml

ci:
  failBelow: 80   # override one key; everything else inherits from base.yml

Multiple parents

Pass an array when you need more than one base. Later entries in the array win on conflict.

extends:
  - ../../.aislop/base.yml
  - ./local-overrides.yml

Merge semantics

Understanding how deep-merge works prevents surprises, especially for arrays.

Value type	Merge behaviour
Nested objects (`engines`, `scoring.weights`, `quality`)	Deep-merged key by key. The child’s keys win on conflict.
Arrays (`exclude`, `include`)	Replaced wholesale. The child’s array replaces the parent’s — values are not concatenated. Include any parent values you want to keep.
Scalars (`ci.failBelow`, `version`, etc.)	The child’s value overwrites the parent’s.

Constraints

Paths are relative to the config file that declares extends:. Absolute paths are also accepted. Package names and URLs are not yet supported and produce a clear error.
Chains deeper than 5 levels are rejected at load time.
Circular references are rejected at load time.

Example configs

The following pre-built configs are available as starting points. Copy one into .aislop/config.yml and adjust from there.

typescript-strict

Tight thresholds for teams that want zero AI slop in production TypeScript code. Raises quality limits, increases all weights, and sets failBelow: 75.

monorepo-relaxed

Looser thresholds for large codebases or early-stage projects adopting aislop incrementally. Sets failBelow: 0 so CI reports scores without blocking.

python-go

Tailored for Python and Go backend services. Increases security weight to 2.5 and extends auditTimeout for slower networks.

Run aislop doctor after editing your config to confirm that every enabled engine has the tools it needs installed.

​Creating the config file

​Full default config

​Top-level sections

​Config inheritance

​Single parent

​Multiple parents

​Merge semantics

​Constraints

​Example configs

typescript-strict

monorepo-relaxed

python-go

Creating the config file

Full default config

Top-level sections

Config inheritance

Single parent

Multiple parents

Merge semantics

Constraints

Example configs