Configuration

Customize diffray behavior with a configuration file.

Quick Start

Create .diffray/config.yaml in your repository:

your-repo/
└── .diffray/
    ├── config.yaml      # Project settings
    └── rules/           # Custom rules (optional)

Full Example

version: 1

# File filters (applied before rule matching)
filters:
  useDefaults: true           # Use built-in exclusions
  exclude:
    - 'vendor/**'
    - '**/*.generated.ts'
  include:
    - 'package.json'          # Re-include specific files

# Review settings
review:
  maxFiles: 150               # Max files per PR (0 = no limit)
  model: sonnet               # AI model (opus/sonnet/haiku)
  minConfidence: 60           # Min confidence to report (0-100)
  minImportance: 1            # Min importance to report (0-10)

# Rules settings
rules:
  # Run only specific rules (all others ignored)
  # only:
  #   - sec_sql_injection
  #   - sec_xss_dangerously_set_html

  # Exclude specific rules
  exclude:
    - doc_missing_jsdoc
    - doc_readme_required

  # Tag-based filtering
  tags:
    only:
      - security
      - bugs
    exclude:
      - documentation
      - style-conventions

  # Agent-based filtering
  agents:
    # only:
    #   - security
    #   - bugs
    exclude:
      - documentation

Settings Reference

filters — File Exclusions

Setting	Default	Description
useDefaults	true	Use built-in exclusions (lock files, node_modules, dist, etc.)
exclude	[]	Additional glob patterns to exclude
include	[]	Patterns to re-include (overrides exclusions)

review — Review Behavior

Setting	Default	Description
maxFiles	150	Max files per PR (0 = no limit)
model	sonnet	AI model for reviews. Options: opus (most capable), sonnet (balanced), haiku (fastest)
minConfidence	60	Minimum confidence threshold (0-100). Only issues with confidence >= this value will be reported
minImportance	1	Minimum importance threshold (0-10). Only issues with importance >= this value will be reported

rules — Rule Filtering

Setting	Default	Description
only	[]	Run only these rule IDs (all others ignored)
exclude	[]	Rule IDs to disable
tags.only	[]	Run only rules with these tags
tags.exclude	[]	Exclude rules with these tags
agents.only	[]	Run only rules from these agents
agents.exclude	[]	Exclude rules from these agents

Available Tags

Rules can be filtered by tags (categories):

Core categories: security, performance, bugs, error-handling, maintainability, readability

Code quality: style-conventions, type-safety, duplication, dead-code

Architecture: architecture, api-design, module-boundaries

Testing & docs: testing, documentation

Compliance: compliance-gdpr, compliance-soc2, compliance-pci-dss, compliance-hipaa, privacy

Languages: typescript, javascript, python, go, java, kotlin, csharp, rust, ruby, php, swift, sql

Frameworks: react, nextjs, vue, angular, nestjs, nodejs, django

Infrastructure: docker, kubernetes, ci-cd, infrastructure

Available Agents

Rules are processed by specialized AI agents:

security, performance, bugs, architecture, quality, consistency, testing, documentation, general

Each agent has expertise in its domain and reviews rules assigned to it.

Example Configurations

Security-Focused Review (by agent)

version: 1

review:
  model: opus           # Use most capable model

rules:
  agents:
    only:
      - security        # Only security agent

Security-Focused Review (by tags)

version: 1

rules:
  tags:
    only:
      - security
      - compliance-soc2

Quick Review (Fast Feedback)

version: 1

review:
  model: haiku          # Fastest model

rules:
  agents:
    exclude:
      - documentation
      - architecture

TypeScript Project

version: 1

rules:
  tags:
    only:
      - typescript
      - security
      - bugs
      - error-handling

React/Next.js Project

version: 1

filters:
  exclude:
    - 'public/**'

rules:
  tags:
    only:
      - react
      - nextjs
      - typescript
      - security
      - performance

Compliance Review

version: 1

review:
  model: opus

rules:
  tags:
    only:
      - compliance-gdpr
      - compliance-soc2
      - compliance-pci-dss
      - security
      - privacy

Finding Rule IDs

To disable a specific rule, you need its ID. Rule IDs appear in:

• Review comments (in parentheses after the issue title)
• Your custom rules in .diffray/rules/*.yaml
• Default rules in core/defaults/rules/

Priority Order

Filters are applied in this order:

1. rules.only — if set, only these rules run (highest priority)
2. rules.exclude — exclude specific rule IDs
3. rules.agents.only — if set, rule's agent must be in the list
4. rules.agents.exclude — exclude rules from specific agents
5. rules.tags.only — if set, rule must have at least one matching tag
6. rules.tags.exclude — exclude rules with any matching tag
7. File pattern matching — rule must match changed files

See Also

• Example Config — full configuration example
• Project-Specific Rules — create custom rules
• Agents — customize AI reviewers
• Writing Effective Rules — best practices