Advanced Configuration

Complete reference for all .anatoly.yml options (schema v2), CLI overrides, and environment variables that control Anatoly's audit behavior.

Overview#

Anatoly reads configuration from a .anatoly.yml file at the project root. If no file exists, all values fall back to schema defaults defined in src/schemas/config.ts. The file is loaded by loadConfig() in src/utils/config-loader.ts, parsed with js-yaml, and validated against ConfigSchema (Zod). A malformed YAML file or an invalid field value throws an AnatolyError with code CONFIG_INVALID.

Generate a commented template interactively via:

anatoly init

Use --force to overwrite an existing file.

The --config <path> global flag loads an alternate file instead of the project-root default:

anatoly run --config ./configs/anatoly.ci.yml

Schema Reference#

project#

scan#

Controls which files are included in each audit run.

The --file <glob> CLI flag narrows the scan scope at runtime without modifying .anatoly.yml.

coverage#

When enabled, Anatoly runs the configured command to produce a JSON coverage report, then attaches coverage data to each file's review task.

providers (v2)#

Declares one or more LLM providers. Each provider entry configures its transport mode (subscription-based CLI vs. direct API), concurrency ceiling, and (for OpenAI-compatible providers) the base_url and env_key.

At least one provider must be configured. anthropic is present by default (mode: subscription, concurrency: 24).

Known providers (see src/core/providers/known-providers.ts):

Unknown providers are accepted as long as they supply a base_url (they are treated as openai-compatible).

providers:
  anthropic:
    mode: subscription
    concurrency: 24

models (v2)#

Selects the concrete model used for each pipeline role. Model strings use provider/model-id form (e.g. anthropic/claude-sonnet-4-6).

code_summary defaults to models.fast (Haiku) and is invoked once per indexed file. Override it to point at any provider/model registered in providers.

agents (v2)#

Controls agentic (multi-turn tool-use) behavior.

runtime (v2)#

Audit-pipeline runtime limits. These replace the former llm.* timing/retry fields from schema v1.

Per-provider SDK concurrency is controlled by providers.<id>.concurrency (not a global runtime field).

axes (v2, top-level)#

Each axis can be individually enabled or disabled, optionally overridden with a specific model, and optionally skipped for matching file globs.

Each axis entry accepts:

axes:
  correction:
    enabled: true
    model: anthropic/claude-opus-4-6
  documentation:
    enabled: false
  tests:
    skip:
      - src/generated/**

The axis-to-model resolution is defined in resolveAxisModel() (src/core/axis-evaluator.ts): per-axis model → else models.fast or models.quality based on the evaluator's default tier.

rag#

Controls the semantic RAG index used for cross-file analysis. RAG mode (lite vs. advanced) is auto-detected from hardware and can be forced with --rag-lite or --rag-advanced. The external mode (third-party provider) is selected by setting rag.embedding.

Each ProviderConfig is { provider: string, model?: string, base_url?: string, env_key?: string }. Either or both axes may be set; if only one is set the other duplicates it at runtime. When rag.embedding is absent, Anatoly falls back to lite or advanced based on hardware detection.

Advanced RAG mode requires Docker with the NVIDIA container toolkit. External mode requires only an HTTPS-reachable provider endpoint and the corresponding API key (e.g. OPENAI_API_KEY, VOYAGE_API_KEY).

logging#

output#

badge#

Controls README badge injection after a completed audit.

documentation#

Anatoly distinguishes two documentation registers: reference (human-authored: READMEs, specs, doc-comments) and internal (curated from code by Anatoly itself, full mode only). The wizard (anatoly init) writes both blocks explicitly.

documentation:
  reference:
    paths: ['README.md', 'docs/**/*.md']
    inline_comments:
      enabled: true
      kinds: ['jsdoc', 'tsdoc']
      include: ['src/**/*.ts']
  internal:
    mode: 'lite'                # 'lite' | 'full' | 'off'
    # full:                     # only present when mode: full
    #   sync_to_repo: false

documentation.reference#

Human-authored docs treated as ground truth by the review axes.

documentation.internal.mode#

Selects how reference documentation reaches the business-logic axes (correction, best-practices, overengineering). No default: the wizard pre-checks lite but the field must be present in the YAML.

lite vs full: the key difference is arbitration#

This is the distinction that matters when choosing a mode.

lite assumes your reference docs are correct and current. The retrieved doc chunks are injected as ground truth with no reconciliation step. If the code contradicts the docs, that contradiction is flagged as a doc_divergence finding against the code (the doc wins by assumption). Choose lite when your docs are actively maintained and you trust them to describe intended behaviour. It is deterministic (cosine similarity, no LLM), cheap, and scales to any doc corpus size because retrieval is per-file rather than whole-corpus.

full does not assume the docs are correct. It generates internal per-module documentation from the code, then runs a 3-way coherence pass that arbitrates between three sources:

1. Reference docs (what humans wrote)
2. Internal docs (what Anatoly derived from the code)
3. Code surface (the actual symbols and signatures)

When reference and code diverge, full mode does not silently pick a winner: it produces doc_divergence findings describing the conflict, and the internal docs are rewritten only to fill gaps the reference docs leave open (never to overrule what the reference docs explicitly state). Curated fragments a human validates via anatoly docs arbitrate are promoted to authoritative "arbitrated intents" and injected alongside the reference docs. Choose full when your docs may be stale or incomplete and you want Anatoly to surface code/doc drift rather than trust the docs blindly.

documentation.internal.full#

Required when mode: full. Omitted entirely for lite and off.

Observability: every RAG retrieval (lite mode per-file lookups, duplication-axis symbol searches, documentation-axis lookups) emits a structured rag.query event into .anatoly/runs/<runId>/anatoly.ndjson with the caller, file, query parameters, latency, and top hit. Grep rag_query to follow the full retrieval chain of any run.

search#

notifications.telegram#

Optional Telegram notifications at run completion.

When enabled: true, either chat_id or username is required.

Examples#

Minimal production config#

# .anatoly.yml
project:
  name: my-api
 
scan:
  include:
    - src/**/*.ts
  exclude:
    - node_modules/**
    - dist/**
    - '**/*.test.ts'
    - '**/*.spec.ts'
 
providers:
  anthropic:
    mode: subscription
 
runtime:
  concurrency: 2
 
output:
  max_runs: 5
 
badge:
  enabled: false

Full annotated config#

# .anatoly.yml — all sections with defaults shown
project:
  name: my-service
  monorepo: false
 
scan:
  include:
    - src/**/*.ts
    - src/**/*.tsx
  exclude:
    - node_modules/**
    - dist/**
    - '**/*.test.ts'
    - '**/*.spec.ts'
 
coverage:
  enabled: true
  command: npx vitest run --coverage.reporter=json
  report_path: coverage/coverage-final.json
 
providers:
  anthropic:
    mode: subscription
    concurrency: 24
 
models:
  quality: anthropic/claude-sonnet-4-6
  fast: anthropic/claude-haiku-4-5-20251001
  deliberation: anthropic/claude-opus-4-6
  # code_summary: anthropic/claude-haiku-4-5     # optional override (defaults to models.fast)
 
agents:
  enabled: true
  max_turns: 30
 
runtime:
  timeout_per_file: 600
  max_retries: 3
  concurrency: 8
  min_confidence: 70
  max_stop_iterations: 3
 
axes:
  utility:         { enabled: true }
  duplication:     { enabled: true }
  correction:      { enabled: true }
  overengineering: { enabled: true }
  tests:           { enabled: true }
  best_practices:  { enabled: true }
  documentation:   { enabled: true }
 
rag:
  enabled: true
  code_model: auto
  nlp_model: auto
  code_weight: 0.6
 
logging:
  level: warn
  file: .anatoly/anatoly.ndjson
  pretty: true
 
output:
  max_runs: 10
 
badge:
  enabled: true
  verdict: false
  link: https://github.com/r-via/anatoly
 
documentation:
  docs_path: docs
  module_mapping:
    auth:
      - docs/auth/overview.md
      - docs/auth/jwt.md
 
search:
  provider: exa
 
notifications:
  telegram:
    enabled: false
    username: myhandle
    bot_token_env: ANATOLY_TELEGRAM_BOT_TOKEN

CLI Flags that Override Config#

The following flags override config values at runtime without modifying .anatoly.yml.

Environment Variables#

Log Level Resolution Priority#

resolveLogLevel() (src/utils/logger.ts) resolves the effective log level using the following priority (highest first):

1. --log-level <level> CLI flag
2. --verbose flag → maps to debug
3. ANATOLY_LOG_LEVEL environment variable
4. Default: warn

See Also#

• 02-Configuration — Initial setup and first config file
• 02-Global-Options — Full list of CLI flags
• run command — Per-run flags and dry-run mode
• init command — Generate a config template