Skip to main content
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:
VariablePurposeRequired
WARDEN_ANTHROPIC_API_KEYClaude API keyYes (unless using Claude Code subscription)
WARDEN_MODELDefault model (lowest priority in precedence chain)No
WARDEN_STATE_DIROverride cache locationNo
WARDEN_SKILL_CACHE_TTLCache TTL in seconds for unpinned remote skillsNo
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

Build docs developers (and LLMs) love

Get started for freeTalk to us