Skip to main content

​
WardenConfig

Root configuration schema for warden.toml.
​
version
1
required
Configuration schema version. Must be 1.
​
defaults
Defaults
default:"undefined"
Default settings inherited by all skills unless overridden
​
skills
SkillConfig[]
default:"[]"
Array of skill configurations defining which analyses to run
​
runner
RunnerConfig
default:"undefined"
Global execution settings for concurrent analysis
​
logs
LogsConfig
default:"undefined"
Log retention and cleanup configuration

​
SkillConfig

Configuration for a single skill.
​
name
string
required
Skill name (must be unique across all skills). Corresponds to a directory in .warden/skills/ or a remote repository.
​
paths
string[]
default:"undefined"
Glob patterns to include (e.g., ["src/**/*.ts", "lib/**/*.js"]). If omitted, analyzes all changed files.
​
ignorePaths
string[]
default:"undefined"
Glob patterns to exclude (e.g., ["**/*.test.ts", "dist/**"]). Overrides paths and defaults.ignorePaths.
​
remote
string
default:"undefined"
Remote repository reference:
  • "owner/repo" - Latest version from default branch
  • "owner/repo@sha" - Specific commit SHA
  • "owner/[email protected]" - Git tag
​
failOn
SeverityThreshold
default:"undefined"
Fail analysis when findings meet this severity: "high", "medium", "low", or "off" to disable.
​
reportOn
SeverityThreshold
default:"undefined"
Only report findings at or above this severity. Filters output but doesn’t affect exit code.
​
maxFindings
number
default:"undefined"
Maximum number of findings to report (must be positive). Truncates output when exceeded.
​
reportOnSuccess
boolean
default:"undefined"
Whether to post a comment when no findings are detected. Useful for PR checks.
​
requestChanges
boolean
default:"false"
Use GitHub’s REQUEST_CHANGES review event when findings exceed failOn severity. Blocks PR merges.
​
failCheck
boolean
default:"false"
Fail the GitHub check run when findings exceed failOn severity. Shows red X in PR checks.
​
model
string
default:"undefined"
Claude model to use (e.g., "claude-sonnet-4-20250514", "claude-opus-4-20250514"). Uses SDK default if omitted.
​
maxTurns
number
default:"50"
Maximum agentic turns (API round-trips) per hunk analysis. Higher values allow more tool use but increase cost.
​
minConfidence
ConfidenceThreshold
default:"undefined"
Minimum confidence level: "high", "medium", "low", or "off". Filters out low-confidence findings.
​
triggers
SkillTrigger[]
default:"undefined"
Defines when and where this skill runs. If omitted, runs on all pull requests with default actions.

​
SkillTrigger

Defines when a skill should run.
​
type
TriggerType
required
Where the trigger runs:
  • "pull_request" - GitHub PR events (requires actions)
  • "local" - Local CLI runs only
  • "schedule" - GitHub Actions cron schedule (requires paths in skill config)
​
actions
string[]
default:"undefined"
Required for pull_request triggers. Array of PR actions to trigger on:
  • ["opened", "synchronize", "reopened"] - Typical configuration
  • ["opened"] - Only when PR is first created
  • ["closed"] - Only when PR is merged or closed
​
schedule
ScheduleConfig
default:"undefined"
Schedule-specific configuration (only used when type is "schedule")

​
Defaults

Global defaults inherited by all skills.
​
failOn
SeverityThreshold
default:"undefined"
Default failure threshold: "high", "medium", "low", or "off"
​
reportOn
SeverityThreshold
default:"undefined"
Default reporting threshold
​
maxFindings
number
default:"undefined"
Default max findings limit
​
reportOnSuccess
boolean
default:"false"
Whether to report when no findings are detected
​
requestChanges
boolean
default:"false"
Use REQUEST_CHANGES review event by default
​
failCheck
boolean
default:"false"
Fail check runs by default
​
model
string
default:"undefined"
Default Claude model for all skills
​
maxTurns
number
default:"50"
Default maximum agentic turns per hunk
​
minConfidence
ConfidenceThreshold
default:"'medium'"
Default minimum confidence level
​
ignorePaths
string[]
default:"undefined"
Global patterns to exclude from all skills (e.g., ["**/node_modules/**", "dist/**"])
​
defaultBranch
string
default:"undefined"
Repository default branch (e.g., "main", "master"). Auto-detected if omitted.
​
chunking
ChunkingConfig
default:"undefined"
Configuration for how files are split and analyzed
​
batchDelayMs
number
default:"0"
Delay in milliseconds between starting concurrent file analyses. Helps avoid rate limiting.
​
auxiliaryMaxRetries
number
default:"5"
Max retries for auxiliary Haiku calls (extraction repair, merging, deduplication, fix evaluation)

​
ChunkingConfig

Controls how files are processed during analysis.
​
filePatterns
FilePattern[]
default:"undefined"
Patterns to control file processing mode
​
coalesce
CoalesceConfig
default:"undefined"
Options for merging nearby diff hunks
​
maxContextFiles
number
default:"50"
Maximum number of “other changed files” to list in hunk prompts for PR context. Set to 0 to disable.

​
FilePattern

Defines how specific files should be processed:
​
pattern
string
required
Glob pattern to match files (e.g., "**/pnpm-lock.yaml", "**/*.svg")
​
mode
'per-hunk' | 'whole-file' | 'skip'
default:"'skip'"
Processing mode:
  • "per-hunk" - Analyze each diff hunk separately (default for most files)
  • "whole-file" - Analyze entire file content at once
  • "skip" - Skip analysis entirely

​
CoalesceConfig

Controls merging of nearby diff hunks:
​
enabled
boolean
default:"true"
Whether to enable hunk coalescing
​
maxGapLines
number
default:"30"
Maximum line gap between hunks to merge them together
​
maxChunkSize
number
default:"8000"
Target maximum size per chunk in characters. Prevents merged chunks from exceeding context limits.

​
ScheduleConfig

Configuration for scheduled skill runs.
​
issueTitle
string
default:"'Warden: {skillName}'"
Title for the tracking issue. Use {skillName} placeholder.
​
createFixPR
boolean
default:"false"
Automatically create PRs with fixes when suggestedFix is available
​
fixBranchPrefix
string
default:"'warden-fix'"
Branch name prefix for fix PRs (e.g., "warden-fix-security-audit")

​
RunnerConfig

Global execution settings.
​
concurrency
number
default:"4"
Maximum concurrent file analyses across all skills (must be positive)

​
LogsConfig

Log file management settings.
​
cleanup
LogCleanupMode
default:"'ask'"
How to handle expired log files:
  • "ask" - Prompt user in TTY (default)
  • "auto" - Silently delete expired logs
  • "never" - Keep all logs indefinitely
​
retentionDays
number
default:"30"
Number of days to retain log files before considering them expired (must be positive)

​
Type Aliases

​
SeverityThreshold

type SeverityThreshold = 'off' | 'high' | 'medium' | 'low';
Used for failOn and reportOn. Setting to "off" disables the threshold.

​
ConfidenceThreshold

type ConfidenceThreshold = 'off' | 'high' | 'medium' | 'low';
Used for minConfidence. Setting to "off" disables filtering.

​
TriggerType

type TriggerType = 'pull_request' | 'local' | 'schedule';

​
LogCleanupMode

type LogCleanupMode = 'ask' | 'auto' | 'never';

​
Example: Complete Configuration

version = 1

[defaults]
failOn = "high"
reportOn = "medium"
minConfidence = "medium"
model = "claude-sonnet-4-20250514"
maxTurns = 50
ignorePaths = ["**/node_modules/**", "dist/**", "**/*.test.ts"]

[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 = "**/*.md"
mode = "whole-file"

[runner]
concurrency = 4

[logs]
cleanup = "auto"
retentionDays = 30

# Security audit skill
[[skills]]
name = "security-audit"
paths = ["src/**/*.ts", "lib/**/*.js"]
failOn = "high"
reportOnSuccess = true

[[skills.triggers]]
type = "pull_request"
actions = ["opened", "synchronize", "reopened"]
requestChanges = true
failCheck = true

# Performance check for local development
[[skills]]
name = "performance-check"
remote = "sentry/[email protected]"
paths = ["src/**/*.ts"]
reportOn = "low"

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

# Weekly security sweep
[[skills]]
name = "weekly-security-sweep"
remote = "sentry/security-skills"
paths = ["**/*.ts", "**/*.js"]
failOn = "off"

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

[skills.triggers.schedule]
issueTitle = "Weekly Security Audit: {skillName}"
createFixPR = true
fixBranchPrefix = "security-fix"

​
Validation

Warden validates warden.toml on load: 
import { WardenConfigSchema, loadConfig } from '@sentry/warden';

// Load and validate from file
const config = await loadConfig('/path/to/warden.toml');

// Parse raw TOML
const parsed = WardenConfigSchema.parse(rawToml);

// Safe parse with error handling
const result = WardenConfigSchema.safeParse(rawToml);
if (!result.success) {
  console.error('Invalid config:', result.error);
}
Warden performs additional validation beyond type checking:
  • Skill names must be unique
  • Schedule triggers require paths to be defined
  • Pull request triggers require actions to be specified

Build docs developers (and LLMs) love

Get started for freeTalk to us