Skip to main content
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

1

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
2

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.
3

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: 2.5
    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.
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.
​
version
number
default:"1"
Config schema version. Must be 1.
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.
​
engines.format
boolean
default:"true"
Formatting checks (Biome, ruff, gofmt, cargo fmt, rubocop, php-cs-fixer).
​
engines.lint
boolean
default:"true"
Language-specific linting (oxlint, ruff, golangci-lint, clippy, expo-doctor).
​
engines.code-quality
boolean
default:"true"
Complexity and dead code: function/file size, deep nesting, unused files and dependencies.
​
engines.ai-slop
boolean
default:"true"
AI-authored pattern detection: narrative comments, swallowed exceptions, as any casts, TODO stubs, generic names, and more.
​
engines.architecture
boolean
default:"false"
Custom import bans, layer enforcement, and required patterns. Requires .aislop/rules.yml. See Architecture Rules.
​
engines.security
boolean
default:"true"
Secrets detection, risky constructs (eval, innerHTML, SQL injection), and dependency audits.
Numeric thresholds that trigger code-quality warnings. See Engines → Quality thresholds for details.
​
quality.maxFunctionLoc
number
default:"80"
Maximum lines of code per function.
​
quality.maxFileLoc
number
default:"400"
Maximum lines of code per file.
​
quality.maxNesting
number
default:"5"
Maximum control-flow nesting depth.
​
quality.maxParams
number
default:"6"
Maximum number of parameters per function.
Options that apply to the lint engine only.
​
lint.typecheck
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.
Options that apply to the security engine only.
​
security.audit
boolean
default:"true"
Run dependency audits (npm audit, pip-audit, cargo audit, govulncheck).
​
security.auditTimeout
number
default:"25000"
Timeout in milliseconds for dependency audit commands. Increase this on slow networks or large dependency trees.
Controls how findings translate into the final 0–100 score.
​
scoring.weights
object
A map of engine name to numeric multiplier. Higher values make that engine’s findings hurt the score more. See Engines → Scoring weights.
​
scoring.thresholds.good
number
default:"75"
Scores at or above this value are labelled Healthy.
​
scoring.thresholds.ok
number
default:"50"
Scores at or above this value (but below good) are labelled Needs Work. Scores below this are Critical.
​
scoring.smoothing
number
default:"20"
Reduces penalty spikes in large repos by dampening the logarithmic density curve. Increase for legacy codebases.
​
scoring.maxPerRule
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.
Settings used when you run aislop ci.
​
ci.failBelow
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.
​
ci.format
string
default:"json"
Output format for aislop ci. Currently "json" is the only supported value.
Controls anonymous usage telemetry.
​
telemetry.enabled
boolean
default:"true"
Set to false to opt out of telemetry entirely. No data is sent when disabled.
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
string[]
Glob patterns for paths to skip during scanning. Replaces the default list entirely when specified — include defaults you want to keep.
​
include
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 typeMerge 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.