Cadence uses YAML configuration files to customize detection thresholds and behavior.

Quick Start

Create a configuration file:

Bash

cadence config init

This creates .cadence.yaml in the current directory. Use it with:

Bash

cadence analyze /path/to/repo --config .cadence.yaml -o report.json

Auto-detection: Without --config, Cadence looks for cadence.yml (not .cadence.yaml) in the current directory. Always pass --config .cadence.yaml when using the generated file to avoid it being silently ignored.

Default Configuration

The full configuration generated by cadence config init:

YAML

# Cadence Configuration - AI-Generated Code Detection

thresholds:
  # SIZE-BASED DETECTION
  suspicious_additions: 500
  suspicious_deletions: 1000
  
  # VELOCITY-BASED DETECTION
  max_additions_per_min: 100
  max_deletions_per_min: 500
  
  # TIMING-BASED DETECTION
  min_time_delta_seconds: 60
  
  # FILE DISPERSION DETECTION
  max_files_per_commit: 50
  
  # RATIO-BASED DETECTION
  max_addition_ratio: 0.95
  min_deletion_ratio: 0.95
  min_commit_size_ratio: 100
  
  # PRECISION ANALYSIS
  enable_precision_analysis: true

# File patterns to exclude from analysis
exclude_files:
  - package-lock.json
  - yarn.lock
  - "*.min.js"
  - "*.min.css"
  - "node_modules/**"
  - "dist/**"
  - "build/**"
  - "out/**"
  - "bin/**"
  - ".next/**"
  - "vendor/**"
  - ".git/**"
  - "*.png"
  - "*.jpg"
  - "*.jpeg"
  - "*.gif"
  - "*.svg"
  - "*.ico"
  - "*.woff"
  - "*.woff2"
  - "*.ttf"
  - "*.eot"
  - "*.otf"

# WEBHOOK SERVER CONFIGURATION
webhook:
  enabled: false
  host: "0.0.0.0"
  port: 8000
  secret: "your-webhook-secret-key-here"
  max_workers: 4
  read_timeout: 30
  write_timeout: 30

# AI ANALYSIS CONFIGURATION (Optional)
ai:
  enabled: false
  provider: "openai"        # "openai" or "anthropic"
  api_key: ""               # or set CADENCE_AI_KEY env var
  model: ""                 # leave empty for provider default
  # OpenAI default: gpt-4o-mini
  # Anthropic default: claude-sonnet-4-20250514

# STRATEGY CONFIGURATION (Optional)
strategies:
  # Set any strategy to false to disable it. All strategies enabled by default.
  # commit_message_analysis: true
  # naming_pattern_analysis: true
  # structural_consistency: true
  # burst_pattern: true
  # error_handling_pattern: true
  # template_pattern: true
  # file_extension_pattern: true
  # statistical_anomaly: true
  # timing_anomaly: true

Understanding Thresholds

Size-Based Detection

suspicious_additions: Flag commits with more additions than this value
- Default: 500 lines
- Higher = less sensitive
- Lower = more sensitive
suspicious_deletions: Flag commits with more deletions than this value
- Default: 1000 lines
- Higher = less sensitive

Example:

Repository with many large commits? Increase to 1000+
Strict code quality? Decrease to 300-400

Velocity-Based Detection

max_additions_per_min: Flag if additions per minute exceeds this
- Default: 100 lines/minute
- Detects abnormally fast code generation
max_deletions_per_min: Flag if deletions per minute exceeds this
- Default: 500 lines/minute

Example:

Automated bulk imports? Increase to 200+
Strict AI detection? Decrease to 50-75

Timing-Based Detection

min_time_delta_seconds: Flag commits within this many seconds of previous commit
- Default: 60 seconds
- Detects rapid-fire commit bursts
- 0 to disable

Example:

Allow quick commits? Increase to 120-300
Very strict? Keep at 30-60

File Dispersion Detection

max_files_per_commit: Flag commits modifying more files than this
- Default: 50 files
- Detects commits affecting too many files

Example:

Large refactors allowed? Increase to 100+
Small focused commits? Decrease to 20-30

Ratio-Based Detection

max_addition_ratio: Flag if additions ratio exceeds this (0.0–1.0)
- Default: 0.95 (95% additions)
- Detects mostly-add commits (suggests generated code)
min_deletion_ratio: Flag if deletion ratio falls below this
- Default: 0.95
- Companion to max_addition_ratio
min_commit_size_ratio: Minimum commit size threshold
- Default: 100

Example:

Allow mostly-additions? Increase max_addition_ratio to 0.98
Strict balance? Decrease to 0.80

Precision Analysis

enable_precision_analysis: Enables advanced structural and pattern-matching strategies
- Default: true
- Disable to speed up analysis on very large repositories

Webhook Server Configuration

YAML

webhook:
  enabled: false         # Set to true to enable the server
  host: "0.0.0.0"        # Bind address
  port: 8000             # Listen port
  secret: ""             # HMAC secret (required when enabled)
  max_workers: 4         # Concurrent analysis workers
  read_timeout: 30       # Request read timeout (seconds)
  write_timeout: 30      # Request write timeout (seconds)

All webhook settings can also be overridden via CLI flags:

Bash

cadence webhook --port 8080 --workers 8 --secret my-secret

See Webhook Server for full setup.

Example:

Allow mostly-additions? Increase to 0.98
Strict balance? Decrease to 0.80

Configuration Presets

Preset 1: Sensitive (Strict)

For detecting even subtle AI patterns:

YAML

thresholds:
  suspicious_additions: 300
  suspicious_deletions: 500
  max_additions_per_min: 50
  max_deletions_per_min: 200
  min_time_delta_seconds: 30
  max_files_per_commit: 20
  max_addition_ratio: 0.80

Use when: Code quality is critical, want to catch subtle issues

Preset 2: Balanced (Default)

Good for most repositories:

YAML

thresholds:
  suspicious_additions: 500
  suspicious_deletions: 1000
  max_additions_per_min: 100
  max_deletions_per_min: 500
  min_time_delta_seconds: 60
  max_files_per_commit: 50
  max_addition_ratio: 0.95

Use when: Want reasonable detection without noise

Preset 3: Permissive (Lenient)

For fast-paced development:

YAML

thresholds:
  suspicious_additions: 1000
  suspicious_deletions: 2000
  max_additions_per_min: 200
  max_deletions_per_min: 1000
  min_time_delta_seconds: 120
  max_files_per_commit: 100
  max_addition_ratio: 0.98

Use when: Large commits/refactors are normal, want minimal false positives

Excluding Files

Prevent certain files from triggering detection:

YAML

exclude_files:
  - package-lock.json
  - yarn.lock
  - "*.min.js"
  - dist/*
  - build/*
  - ".gitignore"

Common patterns to exclude:

Lock files (package-lock.json, Gemfile.lock)
Generated code (dist/, build/, .next/)
Large compiled outputs (*.min.js)
Dependency files (node_modules/)

Optional: AI Analysis

Enable AI-powered expert validation using OpenAI or Anthropic:

YAML

ai:
  enabled: false                    # Set to true to enable
  provider: "openai"                # "openai" or "anthropic"
  model: ""                         # Leave empty for provider default
  api_key: ""                       # Or set via CADENCE_AI_KEY env var

Provider defaults:

OpenAI: gpt-4o-mini
Anthropic: claude-sonnet-4-20250514

Setup AI Analysis

Get API key:
- OpenAI: platform.openai.com/api-keys
- Anthropic: console.anthropic.com

Set environment variable (recommended over embedding in config):

Bash

export CADENCE_AI_ENABLED=true
export CADENCE_AI_PROVIDER=openai
export CADENCE_AI_KEY="sk-..."

Or enable in config with explicit key:

YAML

ai:
  enabled: true
  provider: "openai"  # or "anthropic"
  model: "gpt-4o-mini"

Run analysis:

Bash

cadence analyze /repo --config .cadence.yaml -o report.json

See AI Skills documentation for details on what each AI skill produces.

Using Configuration Files

Auto-detect Configuration

Cadence automatically loads cadence.yml if found in the current directory:

Bash

# In a directory containing cadence.yml
cadence analyze /repo -o report.json
# Automatically uses cadence.yml

Important: cadence config init creates .cadence.yaml (with a leading dot), but auto-detection looks for cadence.yml (no dot, no a). To avoid the config being silently ignored, always pass it explicitly:

Bash

cadence analyze /repo --config .cadence.yaml -o report.json

Explicit Configuration

Specify a configuration file explicitly (works with any name or path):

Bash

cadence analyze /repo --config /path/to/config.yaml -o report.json

Override Individual Settings

Command-line flags override configuration file values:

Bash

cadence analyze /repo \
  --config .cadence.yaml \
  --suspicious-additions 1000 \
  -o report.json
# Uses .cadence.yaml but overrides suspicious_additions

Available override flags:

Flag	Config field	Description
`--suspicious-additions N`	`thresholds.suspicious_additions`	Lines added threshold
`--suspicious-deletions N`	`thresholds.suspicious_deletions`	Lines deleted threshold
`--max-additions-pm N`	`thresholds.max_additions_per_min`	Additions/minute rate
`--max-deletions-pm N`	`thresholds.max_deletions_per_min`	Deletions/minute rate
`--min-time-delta N`	`thresholds.min_time_delta_seconds`	Min seconds between commits
`--branch NAME`	—	Branch to analyze
`--exclude-files PATTERNS`	`exclude_files`	Comma-separated patterns

Strategy Configuration

Enable or disable individual detection strategies. All strategies are enabled by default:

YAML

strategies:
  # Set any to false to disable
  commit_message_analysis: true
  naming_pattern_analysis: true
  structural_consistency: true
  burst_pattern: true
  error_handling_pattern: true
  template_pattern: true
  file_extension_pattern: true
  statistical_anomaly: true
  timing_anomaly: true

Disabling strategies reduces false positives for specific project types. For example, disable burst_pattern for automated dependency update bots.

Using Environment Variables

Configure Cadence via environment variables. These take precedence over config file values for AI settings:

Bash

# AI settings
export CADENCE_AI_ENABLED=true
export CADENCE_AI_PROVIDER=openai     # or: anthropic
export CADENCE_AI_KEY=sk-...          # provider API key
export CADENCE_AI_MODEL=gpt-4o-mini   # optional model override

# Webhook settings (alternative to config file)
export CADENCE_WEBHOOK_PORT=8080
export CADENCE_WEBHOOK_SECRET=my-secret

Configuration Examples

Web Development Project

Projects with auto-generated files, large lock files:

YAML

thresholds:
  suspicious_additions: 750
  suspicious_deletions: 1500
  max_additions_per_min: 150
  max_files_per_commit: 75

exclude_files:
  - package-lock.json
  - yarn.lock
  - "*.min.js"
  - dist/*
  - ".next/*"

Strict Code Quality

Projects requiring high code quality standards:

YAML

thresholds:
  suspicious_additions: 250
  suspicious_deletions: 400
  max_additions_per_min: 40
  max_deletions_per_min: 150
  min_time_delta_seconds: 45
  max_files_per_commit: 15
  max_addition_ratio: 0.75

Data Science / ML Project

Projects with data files and large generated outputs:

YAML

thresholds:
  suspicious_additions: 2000
  suspicious_deletions: 3000
  max_additions_per_min: 300
  max_files_per_commit: 100

exclude_files:
  - "*.pkl"
  - "*.h5"
  - "*.pth"
  - "*.joblib"
  - data/*

Enterprise Repository

Large enterprise projects with many contributors:

YAML

thresholds:
  suspicious_additions: 1000
  suspicious_deletions: 2000
  max_additions_per_min: 200
  max_files_per_commit: 80
  max_addition_ratio: 0.97

ai:
  enabled: true
  model: gpt-4o-mini

Per-Repository Configuration

Use different configurations for different projects:

Bash

# Project A with strict rules
cadence analyze ~/projects/projectA --config ~/.cadence/strict.yaml -o report.json

# Project B with lenient rules
cadence analyze ~/projects/projectB --config ~/.cadence/lenient.yaml -o report.json

# Project C with custom rules
cadence analyze ~/projects/projectC --config ./cadence.yaml -o report.json

Troubleshooting Configuration

"Config file not found"

Make sure the file exists and path is correct:

Bash

# Check file exists
ls -la .cadence.yaml

# Use full path to be safe
cadence analyze /repo --config $(pwd)/.cadence.yaml -o report.json

Remember: cadence config init creates .cadence.yaml, but auto-detection looks for cadence.yml. Use --config .cadence.yaml explicitly.

Thresholds Have No Effect

Verify configuration is being loaded. Check if flags are overriding config:

Bash

# This overrides config value
cadence analyze /repo --config .cadence.yaml --suspicious-additions 2000 -o report.json

# Use config only (no override flags)
cadence analyze /repo --config .cadence.yaml -o report.json

Also confirm the config file name: cadence config init creates .cadence.yaml, not cadence.yml.

AI Analysis Not Working

Ensure:

API key is set: echo $CADENCE_AI_KEY
Config has enabled: true or CADENCE_AI_ENABLED=true
Valid API key (OpenAI starts with sk-proj- or sk-, Anthropic starts with sk-ant-)
Provider matches the API key type

Bash

# Verify env vars
echo $CADENCE_AI_ENABLED
echo $CADENCE_AI_PROVIDER
echo $CADENCE_AI_KEY

Next Steps

CLI Commands - Learn all available commands
Quick Start - Run your first analysis
Detection Strategies - Understand what gets detected