Guide

Warden watches over your code by running skills against your changes. Skills are prompts that define what to look for: security vulnerabilities, API design issues, performance problems, or anything else you want consistent coverage on.

The Core Idea

Every time you run Warden, it:

  1. Identifies what changed (files, hunks, or entire directories)
  2. Matches changes against configured triggers
  3. Runs the appropriate skills against matching code
  4. Reports findings with severity, location, and optional fixes

Skills follow the agentskills.io specification -they're markdown files with a prompt that tells the AI what to look for. You can use community skills, write your own, or combine both.

Warden works in two contexts:

When to Use Warden

Use Warden when:

Skip Warden when:

Local Development

Running Warden locally is the fastest way to get value. You get feedback before pushing, while the code is fresh in your mind.

Authentication

Warden uses your Claude Code subscription if you're logged in. Otherwise, set an API key:

# Option 1: Claude Code subscription (if logged in)
claude login

# Option 2: API key
export WARDEN_ANTHROPIC_API_KEY=sk-ant-...

Get an API key from console.anthropic.com. CI/CD environments require an API key.

Review Uncommitted Changes

Run Warden with no arguments to review your working directory:

warden

Warden analyzes staged and unstaged changes, running any skills that match via your configured triggers.

Review Before Pushing

Review all commits on your branch that aren't on main:

warden main..HEAD

This catches everything you're about to push.

Run a Specific Skill

Skip trigger matching and run one skill directly:

warden --skill security-review

Auto-Fix Issues

Let Warden apply suggested fixes interactively:

warden --fix

You'll be prompted to accept or reject each fix.

Analyze Specific Files

Target specific files or directories:

warden src/auth.ts
warden src/api/

Creating Skills

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

Directory Structure

Create a skill in one of these directories (first match wins):

.warden/skills/skill-name/SKILL.md   # Warden-specific (highest priority)
.agents/skills/skill-name/SKILL.md   # Shared agent skills
.claude/skills/skill-name/SKILL.md   # Claude Code skills

SKILL.md Format

A skill has YAML frontmatter for metadata and markdown for the prompt:

---
name: security-review
description: Review code for security vulnerabilities
allowed-tools: Read Grep Glob
---

Review the code for security issues including:
- SQL injection and parameter binding
- XSS vulnerabilities in user input handling
- Hardcoded secrets or credentials
- Insecure cryptographic practices
- Path traversal vulnerabilities

Focus on issues in the changed code. For each issue found, report:
- The specific vulnerability type
- Why it's a problem
- How to fix it

Frontmatter Fields

name
Skill identifier (referenced in triggers and CLI)
description
Brief description of what the skill does
allowed-tools
Space-separated list of tools the skill can use

Available Tools

Read, Grep, Glob, Edit, Write, Bash, WebFetch, WebSearch

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

What Makes a Good Skill

Adding Skills

Warden can discover and install community skills.

Interactive Mode

warden add

Browse available skills and select which to add.

List Available Skills

warden add --list

Add a Specific Skill

warden add security-review

This adds the skill and creates a trigger in warden.toml.

Pull Request Reviews

Warden runs automatically on pull requests via GitHub Actions, posting findings as review comments.

Organization Setup

Add your Anthropic API key as an organization secret so all repos can use it:

  1. Go to Organization Settings → Secrets and variables → Actions
  2. Add WARDEN_ANTHROPIC_API_KEY with your key from console.anthropic.com

Repository Setup

Initialize Warden in each repository:

npx warden init

This creates:

What Happens on a PR

  1. PR is opened or updated
  2. GitHub Actions runs the Warden workflow
  3. Warden analyzes changed files against configured triggers
  4. Findings are posted as inline review comments
  5. Check passes or fails based on failOn severity

Configuring Triggers

Triggers map events to skills. Edit warden.toml:

version = 1

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

[[triggers]]
name = "API Review"
event = "pull_request"
actions = ["opened", "synchronize"]
skill = "api-review"

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

See the Config reference for all trigger options.

Controlling Output

Configure when to fail and what to comment on:

[defaults.output]
failOn = "high"      # Fail the check on high or critical findings
commentOn = "medium" # Post comments for medium and above

GitHub App (Optional)

By default, Warden posts comments as "github-actions". Create a GitHub App for branded comments that appear from "Warden" with a custom avatar.

Create the App

npx warden setup-app --org your-org

This opens a browser to create and install the app.

Add Secrets

Add these to your organization secrets:

WARDEN_APP_ID
App ID from the setup command output
WARDEN_PRIVATE_KEY
Private key (full PEM contents)

Update Workflow

Uncomment the GitHub App section in .github/workflows/warden.yml:

- uses: actions/create-github-app-token@v1
  id: app-token
  with:
    app-id: ${{ secrets.WARDEN_APP_ID }}
    private-key: ${{ secrets.WARDEN_PRIVATE_KEY }}

- uses: getsentry/warden@v0
  with:
    github-token: ${{ steps.app-token.outputs.token }}

Tips

See the CLI reference for all options.