Configuration¶

Configuration is loaded from zen-config.yaml in the current directory or the nearest parent containing pyproject.toml. Run zen init to generate one interactively.

How configuration works¶

The config file controls three things:

1. Which languages are enabled — only enabled languages get analyzed
2. Pipeline overrides — tune thresholds per detector type
3. Severity threshold — set the minimum severity that triggers a non-zero exit code

Ignore files during analysis¶

When scanning directories, Zen excludes files and folders matched by:

• .gitignore
• .zen-of-languages.ignore

Running zen init creates a starter .zen-of-languages.ignore if it does not already exist.

Basic example¶

yaml version: 1 languages: python: enabled: true pipeline: - type: cyclomatic-complexity max_cyclomatic_complexity: 10 - type: nesting-depth max_nesting_depth: 4 typescript: enabled: true pipeline: - type: any-usage max_any_count: 0

yaml version: 1 severity_threshold: 6 languages: python: enabled: true pipeline: - type: cyclomatic-complexity max_cyclomatic_complexity: 7 - type: function-length max_function_length: 35

yaml version: 1 severity_threshold: 8 languages: python: enabled: true typescript: enabled: true # All detectors use their default thresholds

Choosing thresholds¶

Begin with default thresholds. Run zen reports . to see your baseline. Then lower limits on the detectors that matter most to your team.

Override behavior¶

Pipeline entries override detector defaults by type. If you list a detector in the pipeline, your values replace its defaults. If you omit a detector, it uses the values derived from the language's zen rules.

pipeline:
  - type: cyclomatic-complexity
    max_cyclomatic_complexity: 7 # overrides default of 10
  # nesting-depth not listed → uses rule-derived default

Per-language configuration¶

Each language has its own set of detector config fields. See the config reference for all fields, or check the individual language pages:

• Python detectors — 23 detectors with AST-based analysis
• TypeScript detectors — 10 type-safety focused detectors
• Rust detectors — 13 safety and idiom detectors
• All languages — Full comparison table

Monorepo strategy¶

For monorepos with multiple languages or packages:

# Per-package config
zen reports packages/frontend --config packages/frontend/zen-config.yaml
zen reports packages/backend --config packages/backend/zen-config.yaml

Each package can have its own thresholds — strict for new code, relaxed for legacy modules.

Environment variables¶

Configuration¶

MCP Server (FastMCP)¶

When running mcp-zen-of-languages-server (legacy alias: zen-mcp-server), these FastMCP environment variables control server behavior:

Example:

{
  "env": {
    "ZEN_CONFIG_PATH": "${workspaceFolder}/zen-config.yaml",
    "FASTMCP_DEBUG": "true",
    "FASTMCP_LOG_LEVEL": "DEBUG"
  }
}

This enables verbose logging useful for troubleshooting MCP integration issues.

See Also¶

• CLI Reference — All command flags
• Config Reference — Auto-generated list of all config fields