/warden

Configuration (warden.toml)

See config-schema.md for the complete schema reference.

Minimal Example

The name field references a skill you've created (via warden add) or defined in .agents/skills/<name>/SKILL.md. Use that same name everywhere — in config, CLI flags, and triggers.

version = 1

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

[[skills]]
name = "my-skill"           # matches .agents/skills/my-skill/SKILL.md
paths = ["src/**/*.ts"]

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

Skill Configuration

Skills define what to analyze and when. Each skill requires a name. Triggers are optional — skills with no triggers run everywhere (PR, local, schedule). All skills run locally regardless of trigger type.

[[skills]]
name = "my-skill"
paths = ["src/auth/**", "src/payments/**"]
failOn = "high"
reportOn = "medium"
maxFindings = 20

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

Trigger types: pull_request, local (local-only), schedule (CI-only)

Actions (pull_request): opened, synchronize, reopened, closed

Common Patterns

Strict checks on critical files:

[[skills]]
name = "my-skill"
model = "claude-opus-4-20250514"
maxTurns = 100
paths = ["src/auth/**", "src/payments/**"]
failOn = "high"

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

Skip test files:

[[skills]]
name = "my-skill"
paths = ["src/**/*.ts"]
ignorePaths = ["**/*.test.ts", "**/*.spec.ts"]

Whole-file analysis for configs:

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

Model Precedence

From highest to lowest priority:

1. Skill-level model
2. [defaults] model
3. CLI --model flag
4. WARDEN_MODEL env var
5. SDK default

Environment Variables

Troubleshooting

No findings reported:

• Check --report-on threshold (default shows all)
• Verify skill matches file types in paths
• Use -v to see which files are being analyzed

Files being skipped:

• Built-in skip patterns: lock files, minified, node_modules/, dist/
• Check ignorePaths in config
• Use -vv to see skip reasons

Token/cost issues:

• Reduce maxTurns (default: 50)
• Use chunking settings to control chunk size
• Filter to relevant files with paths