warden.toml Reference

Complete reference for Warden’s configuration file

The warden.toml file controls all aspects of Warden’s behavior. Place it at the root of your repository.

File Structure

version = 1

[defaults]
# Global defaults inherited by all skills

[[skills]]
# Individual skill configuration

[[skills.triggers]]
# When and where the skill runs

[runner]
# Runtime behavior

[logs]
# Log management

Version

version · number · required

Configuration schema version. Must be 1.

version = 1

Defaults Section

Settings applied to all skills unless overridden at the skill or trigger level.

Output Control

defaults.failOn · enum

Exit with code 1 when findings meet this severity threshold.

Values: "off", "high", "medium", "low"
Default: Not set (never fails)

[defaults]
failOn = "high"  # Fail on high severity findings

defaults.reportOn · enum

Only show findings at or above this severity level.

Values: "off", "high", "medium", "low"
Default: Shows all findings

[defaults]
reportOn = "medium"  # Hide low severity findings

defaults.maxFindings · number

Maximum number of findings to report per skill run.

Default: Unlimited
Minimum: 1

[defaults]
maxFindings = 50

defaults.reportOnSuccess · boolean

Post a report even when no findings are detected.

Default: false

[defaults]
reportOnSuccess = true

defaults.minConfidence · enum

Filter out findings below this confidence level.

Values: "off", "high", "medium", "low"
Default: "medium"

[defaults]
minConfidence = "high"  # Only show high confidence findings

GitHub Integration

defaults.requestChanges · boolean

Use REQUEST_CHANGES review event when findings exceed failOn threshold.

Default: false

[defaults]
requestChanges = true

defaults.failCheck · boolean

Fail the GitHub Actions check run when findings exceed failOn threshold.

Default: false

[defaults]
failCheck = true

Model Configuration

defaults.model · string

Default Claude model for all skills.

Example values: "claude-sonnet-4-20250514", "claude-opus-4-20250514"
Default: SDK default model

[defaults]
model = "claude-sonnet-4-20250514"

defaults.maxTurns · number

Maximum agentic turns (API round-trips) per hunk analysis.

Default: 50
Minimum: 1

[defaults]
maxTurns = 100  # Allow deeper analysis

Repository Settings

defaults.defaultBranch · string

Base branch for comparisons (e.g., main, master, develop).

Default: Auto-detected from repository

[defaults]
defaultBranch = "main"

defaults.ignorePaths · array

Path patterns to exclude from all skill analyses. Uses glob syntax.

[defaults]
ignorePaths = ["dist/**", "**/*.test.ts", "evals/**"]

Performance Tuning

defaults.batchDelayMs · number

Delay in milliseconds between batch starts when processing files in parallel.

Default: 0 (no delay)
Minimum: 0

[defaults]
batchDelayMs = 1000  # 1 second delay between batches

defaults.auxiliaryMaxRetries · number

Max retries for auxiliary Haiku calls (extraction repair, merging, deduplication, fix evaluation).

Default: 5
Minimum: 1

[defaults]
auxiliaryMaxRetries = 3

Chunking Configuration

See Path Filtering for detailed chunking options.

[defaults.chunking]
maxContextFiles = 50

[defaults.chunking.coalesce]
enabled = true
maxGapLines = 30
maxChunkSize = 8000

[[defaults.chunking.filePatterns]]
pattern = "**/*.config.*"
mode = "whole-file"

Runner Section

Controls Warden’s runtime behavior.

runner.concurrency · number

Maximum concurrent file analyses across all skills.

Default: 4
Minimum: 1

[runner]
concurrency = 8  # Analyze 8 files simultaneously

Logs Section

Manages log file retention and cleanup.

logs.cleanup · enum

How to handle expired log files.

Values:

• "ask" - Prompt in TTY before deletion (default)
• "auto" - Silently delete expired logs
• "never" - Keep all logs indefinitely

[logs]
cleanup = "auto"

logs.retentionDays · number

Number of days to retain log files before considering them expired.

Default: 30
Minimum: 1

[logs]
retentionDays = 7

Complete Example

version = 1

[defaults]
# Output control
failOn = "high"
reportOn = "medium"
maxFindings = 50
minConfidence = "medium"

# Model settings
model = "claude-sonnet-4-20250514"
maxTurns = 50

# Repository
defaultBranch = "main"
ignorePaths = ["dist/**", "**/*.test.ts"]

# GitHub integration
requestChanges = false
failCheck = false

[defaults.chunking]
maxContextFiles = 50

[defaults.chunking.coalesce]
enabled = true
maxGapLines = 30
maxChunkSize = 8000

[[defaults.chunking.filePatterns]]
pattern = "**/pnpm-lock.yaml"
mode = "skip"

[[defaults.chunking.filePatterns]]
pattern = "**/*.config.*"
mode = "whole-file"

[runner]
concurrency = 4

[logs]
cleanup = "ask"
retentionDays = 30

[[skills]]
name = "security-review"
paths = ["src/**/*.ts"]
ignorePaths = ["**/*.test.ts"]
failOn = "high"

[[skills.triggers]]
type = "pull_request"
actions = ["opened", "synchronize"]

[[skills]]
name = "code-quality"
remote = "getsentry/sentry-skills"

[[skills.triggers]]
type = "local"

Environment Variables

These environment variables affect Warden’s behavior:

Variable	Purpose	Required
WARDEN_ANTHROPIC_API_KEY	Claude API key	Yes (unless using Claude Code subscription)
WARDEN_MODEL	Default model (lowest priority in precedence chain)	No
WARDEN_STATE_DIR	Override cache location	No
WARDEN_SKILL_CACHE_TTL	Cache TTL in seconds for unpinned remote skills	No

export WARDEN_ANTHROPIC_API_KEY="sk-ant-..."
export WARDEN_MODEL="claude-sonnet-4-20250514"
export WARDEN_STATE_DIR="~/.cache/warden"
export WARDEN_SKILL_CACHE_TTL="3600"  # 1 hour

Environment variables have lower precedence than configuration file settings. See Model Precedence for the complete hierarchy.

Validation

Warden validates your configuration on startup using Zod schemas. Common validation errors:

Duplicate skill names: Each skill must have a unique name.

# ❌ Invalid - duplicate names
[[skills]]
name = "my-skill"

[[skills]]
name = "my-skill"  # Error!

Schedule triggers require paths: Skills with schedule triggers must specify which files to analyze.

# ❌ Invalid - schedule without paths
[[skills]]
name = "nightly-scan"

[[skills.triggers]]
type = "schedule"  # Error: paths required!

# ✅ Valid
[[skills]]
name = "nightly-scan"
paths = ["src/**/*.ts"]

[[skills.triggers]]
type = "schedule"

Pull request triggers require actions: Specify which PR events should trigger the skill.

# ❌ Invalid - missing actions
[[skills.triggers]]
type = "pull_request"  # Error: actions required!

# ✅ Valid
[[skills.triggers]]
type = "pull_request"
actions = ["opened", "synchronize"]

Next Steps

Skill Configuration

Learn about individual skill settings

Triggers

Configure when and where skills run

Path Filtering

Control which files are analyzed

Severity Thresholds

Fine-tune finding severity and confidence levels