Warden Skill

Warden Usage

Warden is an event-driven AI agent that analyzes code changes and executes configurable skills to produce structured reports with findings.

Quick Start

# Set API key
export WARDEN_ANTHROPIC_API_KEY=sk-ant-...

# Analyze uncommitted changes (uses warden.toml triggers)
warden

# Run specific skill on uncommitted changes
warden --skill find-bugs

# Analyze specific files
warden src/auth.ts src/database.ts

# Analyze changes from git ref
warden main..HEAD
warden HEAD~3

CLI Reference

warden [command] [targets...] [options]

Commands:

• (default) - Run analysis
• init - Initialize warden.toml and GitHub workflow
• add [skill] - Add skill trigger to warden.toml
• sync [repo] - Update cached remote skills to latest
• setup-app - Create GitHub App via manifest flow

Targets:

• <files> - Specific files (e.g., src/auth.ts)
• <glob> - Pattern match (e.g., src/**/*.ts)
• <git-ref> - Git range (e.g., main..HEAD, HEAD~3)
• (none) - Uncommitted changes

Key Options:

Severity levels: critical, high, medium, low, info, off

Configuration (warden.toml)

See references/config-schema.md for complete schema.

Minimal example:

version = 1

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

[[triggers]]
name = "find-bugs"
event = "pull_request"
actions = ["opened", "synchronize"]
skill = "find-bugs"

[triggers.filters]
paths = ["src/**/*.ts"]

With custom output thresholds:

[[triggers]]
name = "security-strict"
event = "pull_request"
actions = ["opened", "synchronize"]
skill = "security-review"

[triggers.filters]
paths = ["src/auth/**", "src/payments/**"]

[triggers.output]
failOn = "critical"
commentOn = "high"
maxFindings = 20

Creating Custom Skills

Skills live in .warden/skills/, .agents/skills/, or .claude/skills/.

Structure:

.warden/skills/my-skill/
└── SKILL.md

SKILL.md format:

---
name: my-skill
description: What this skill analyzes
allowed-tools: Read Grep Glob
---

[Analysis instructions for the agent]

## What to Look For
- Specific issue type 1
- Specific issue type 2

## Output Format
Report findings with severity, location, and suggested fix.

Available tools: Read, Glob, Grep, WebFetch, WebSearch, Bash, Write, Edit

Remote Skills

Skills can be fetched from GitHub repositories:

# Add a remote skill
warden add --remote getsentry/skills --skill security-review

# Add with version pinning (recommended for reproducibility)
warden add --remote getsentry/skills@abc123 --skill security-review

# List skills in a remote repo
warden add --remote getsentry/skills --list

# Update all unpinned remote skills
warden sync

# Update specific repo
warden sync getsentry/skills

# Run with cached skills only (no network)
warden --offline

Remote trigger in warden.toml:

[[triggers]]
name = "security-review"
event = "pull_request"
actions = ["opened", "synchronize"]
skill = "security-review"
remote = "getsentry/skills@abc123"

Cache location: ~/.local/warden/skills/ (override with WARDEN_STATE_DIR)

Cache TTL: 24 hours for unpinned refs (override with WARDEN_SKILL_CACHE_TTL in seconds)

Common Patterns

Strict security on critical files:

[[triggers]]
name = "auth-security"
event = "pull_request"
actions = ["opened", "synchronize"]
skill = "security-review"
model = "claude-opus-4-20250514"
maxTurns = 100

[triggers.filters]
paths = ["src/auth/**", "src/payments/**"]

[triggers.output]
failOn = "critical"

Skip test files:

[triggers.filters]
paths = ["src/**/*.ts"]
ignorePaths = ["**/*.test.ts", "**/*.spec.ts"]

Whole-file analysis for configs:

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

Troubleshooting

No findings reported:

• Check --comment-on threshold (default shows all)
• Verify skill matches file types in filters.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

warden.toml Configuration Schema

Top-Level Structure

version = 1                    # Required, must be 1

[defaults]                     # Optional, inherited by all triggers
[[triggers]]                   # Required, array of trigger configs

Defaults Section

[defaults]
model = "claude-sonnet-4-20250514"    # Default model
maxTurns = 50                         # Max agentic turns per hunk
defaultBranch = "main"                # Base branch for comparisons

[defaults.output]
failOn = "high"                # Exit 1 if findings >= this severity
commentOn = "medium"           # Show findings >= this severity
maxFindings = 50               # Max findings to report (0 = unlimited)
commentOnSuccess = false       # Post comment even with no findings

[defaults.filters]
paths = ["src/**/*.ts"]        # Include only matching files
ignorePaths = ["*.test.ts"]    # Exclude matching files

[defaults.chunking]
enabled = true                 # Enable hunk-based chunking

[defaults.chunking.coalesce]
enabled = true                 # Merge nearby hunks
maxGapLines = 30               # Lines between hunks to merge
maxChunkSize = 8000            # Max chars per chunk

[[defaults.chunking.filePatterns]]
pattern = "*.config.*"         # Glob pattern
mode = "whole-file"            # per-hunk | whole-file | skip

Triggers Section

[[triggers]]
name = "trigger-name"          # Required, unique identifier
event = "pull_request"         # Required: pull_request | issues | issue_comment | schedule
actions = ["opened", "synchronize"]  # Required for non-schedule events
skill = "find-bugs"            # Required, skill name or path
remote = "owner/repo@sha"      # Optional, fetch skill from GitHub repo

# Optional overrides (inherit from defaults if not set)
model = "claude-opus-4-20250514"
maxTurns = 100

[triggers.filters]
paths = ["src/**"]
ignorePaths = ["**/*.test.ts"]

[triggers.output]
failOn = "critical"
commentOn = "high"
maxFindings = 20
commentOnSuccess = true

# Schedule-specific (only for event = "schedule")
[triggers.schedule]
issueTitle = "Daily Security Review"   # GitHub issue title for tracking
createFixPR = true                     # Create PR with fixes
fixBranchPrefix = "security-fix"       # Branch name prefix

Event types:

• pull_request - Triggers on PR events
• issues - Triggers on issue events
• issue_comment - Triggers on issue/PR comments
• schedule - Triggers on cron schedule (GitHub Action)

Actions (for non-schedule):

• opened, synchronize, reopened, closed

Severity Values

Used in failOn and commentOn:

• critical - Most severe
• high
• medium
• low
• info - Least severe
• off - Disable threshold

Built-in Skip Patterns

Always skipped (cannot be overridden):

• Package locks: pnpm-lock.yaml, package-lock.json, yarn.lock, Cargo.lock, etc.
• Minified files: **/*.min.js, **/*.min.css
• Build artifacts: dist/, build/, node_modules/, .next/, __pycache__/
• Generated code: *.generated.*, *.g.ts, __generated__/

Environment Variables

Model Precedence (highest to lowest)

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