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
  google:
    mode: api
    concurrency: 10

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, google/gemini-2.5-flash-lite).

code_summary is typically pointed at a cheap/fast non-Claude model (e.g. google/gemini-2.5-flash-lite) to offload the Claude quota — it is invoked once per indexed file. When unset, models.fast (Haiku) is used.

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#

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

Dual-provider config (Anthropic + Gemini for summaries)#

# .anatoly.yml
project:
  name: my-service
 
providers:
  anthropic:
    mode: subscription
    concurrency: 24
  google:
    mode: api
    concurrency: 10
    env_key: GOOGLE_GENERATIVE_AI_API_KEY
 
models:
  quality: anthropic/claude-sonnet-4-6
  fast: anthropic/claude-haiku-4-5-20251001
  deliberation: anthropic/claude-opus-4-6
  code_summary: google/gemini-2.5-flash-lite
 
axes:
  correction:
    model: anthropic/claude-opus-4-6
  duplication:
    model: google/gemini-2.5-flash

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: google/gemini-2.5-flash-lite   # optional — offloads RAG summaries off the Claude quota
 
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