Warden

Run Warden to analyze code changes before committing.

References

Read the relevant reference when the task requires deeper detail:

Running Warden

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

# Run a specific skill
warden --skill <skill-name>

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

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

# Auto-apply suggested fixes
warden --fix

# Fail on high-severity findings
warden --fail-on high

Set WARDEN_ANTHROPIC_API_KEY or log in via claude login before running.

Pre-Commit Workflow

After making code changes and before committing:

1. Run warden to analyze uncommitted changes 2. Review the findings 3. Fix issues Warden reports (or use warden --fix to auto-apply) 4. Commit the changes

Run Warden once to validate work. Do not loop re-running Warden on the same changes.

Reading Output

Severity levels:

• high - Must fix before merge
• medium - Worth reviewing
• low - Minor improvement

Exit codes: 0 = no findings at or above fail threshold. 1 = findings at or above fail threshold.

Verbosity: -v shows real-time findings. -vv shows debug info (tokens, latency). -q shows errors and summary only.

Commands

For full options and flags, read ${CLAUDE_SKILL_ROOT}/references/cli-reference.md.

CLI Reference

Usage

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

Analyze code for security issues and code quality.

Commands

Targets

Ambiguous targets (no path separator, no extension) are resolved by checking if a file exists at the path. Use --git to force git ref interpretation.

Options

Per-Command Options

Init:

Add:

Sync:

Setup-app:

Severity Levels

Used in --fail-on and --report-on:

Exit Codes

Examples

# Initialize
warden init

# Interactive skill selection
warden add
warden add <skill-name>
warden add --list

# Remote skills
warden add --remote <org>/<repo> --skill <skill-name>
warden add --remote https://github.com/<org>/<repo> --skill <skill-name>
warden add --remote <org>/<repo>@<ref> --skill <skill-name>

# Run analysis
warden                                  # Skills from warden.toml
warden src/auth.ts                      # Specific file
warden src/auth.ts --skill <skill-name>
warden "src/**/*.ts"                    # Glob pattern
warden HEAD~3                           # Git changes
warden HEAD~3 --skill <skill-name>
warden main..HEAD                       # Branch diff

# Output control
warden --json
warden --fail-on high
warden -o results.jsonl

# Fix mode
warden --fix

# Cached skills only
warden --offline
warden sync                             # Update all unpinned remote skills

# GitHub App setup
warden setup-app
warden setup-app --org myorg

warden.toml Configuration Schema

Top-Level Structure

version = 1                    # Required, must be 1

[defaults]                     # Optional, inherited by all skills
[[skills]]                     # Required, array of skill configs

Defaults Section

[defaults]
model = "claude-sonnet-4-20250514"    # Default model
maxTurns = 50                         # Max agentic turns per hunk
defaultBranch = "main"                # Base branch for comparisons
failOn = "high"                # Exit 1 if findings >= this severity
reportOn = "medium"            # Show findings >= this severity
maxFindings = 50               # Max findings to report (0 = unlimited)
reportOnSuccess = false        # Post report even with no findings
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

Skills Section

[[skills]]
name = "skill-name"            # Required, unique identifier
remote = "owner/repo@sha"      # Optional, fetch skill from GitHub repo
paths = ["src/**"]             # Include only matching files
ignorePaths = ["**/*.test.ts"] # Exclude matching files

# Optional overrides (inherit from defaults if not set)
model = "claude-opus-4-20250514"
maxTurns = 100
failOn = "high"
reportOn = "medium"
maxFindings = 20
reportOnSuccess = true

[[skills.triggers]]
type = "pull_request"          # Required: pull_request | local | schedule
actions = ["opened", "synchronize"]  # Required for pull_request

# Schedule-specific (only for type = "schedule")
[[skills.triggers]]
type = "schedule"

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

Trigger types:

• pull_request - Triggers on PR events
• local - Local CLI only (will not run in CI)
• schedule - Cron schedule (GitHub Action only)

All skills run locally regardless of trigger type. Skills with no triggers run everywhere (wildcard). Use type = "local" for skills that should only run locally.

Actions (for pull_request):

• opened, synchronize, reopened, closed

Severity Values

Used in failOn and reportOn:

• high - Must fix before merge
• medium - Worth reviewing
• low - Minor improvement
• 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. Skill-level model 2. [defaults] model 3. CLI --model flag 4. WARDEN_MODEL env var 5. SDK default

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

Creating Skills

Skills are markdown files that tell Warden what to look for. They follow the agentskills.io specification.

Skill Discovery

Warden searches these directories in order (first match wins):

.agents/skills/{name}/SKILL.md   # Primary (recommended)
.claude/skills/{name}/SKILL.md   # Backup (Claude Code convention)

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

Most review skills only need Read, Grep, and Glob for exploring context.

Writing Checklist

• One skill, one concern ("security review" not "code quality")
• Clear criteria for what counts as an issue and at what severity
• Actionable findings that include how to fix
• Examples of good and bad code where helpful

Remote Skills

Skills can be fetched from GitHub repositories:

# Add a remote skill
warden add --remote <org>/<repo> --skill <skill-name>

# Add with version pinning (recommended for reproducibility)
warden add --remote <org>/<repo>@<ref> --skill <skill-name>

# List skills in a remote repo
warden add --remote <org>/<repo> --list

# Update all unpinned remote skills
warden sync

# Update specific repo
warden sync <org>/<repo>

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

Remote skill in warden.toml:

[[skills]]
name = "my-skill"
remote = "<org>/<repo>@<ref>"

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

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)