Skip to main content
Warden exposes a clean TypeScript API for programmatic code analysis. Import it as a library to run skills, build event contexts, match triggers, and render reports.

​
Installation

npm install @sentry/warden

​
Core Workflow

The typical workflow for using Warden programmatically:
  1. Load configuration - Parse warden.toml and resolve skill configs
  2. Build event context - Create an EventContext from GitHub events or local files
  3. Match triggers - Determine which skills should run for the given context
  4. Run skills - Execute Claude-powered analysis on code changes
  5. Render output - Format findings as GitHub reviews or markdown
import { 
  loadWardenConfig,
  resolveSkillConfigs,
  buildEventContext,
  matchTrigger,
  runSkill,
  renderSkillReport 
} from '@sentry/warden';

// 1. Load config
const config = loadWardenConfig('/path/to/repo');
const triggers = resolveSkillConfigs(config);

// 2. Build context from GitHub webhook
const context = await buildEventContext(
  'pull_request',
  eventPayload,
  '/path/to/repo',
  octokit
);

// 3. Match triggers
const matchedTriggers = triggers.filter(t => 
  matchTrigger(t, context, 'github')
);

// 4. Run analysis
for (const trigger of matchedTriggers) {
  const skill = await resolveSkillAsync(trigger.name, '/path/to/repo');
  const report = await runSkill(skill, context, {
    apiKey: process.env.WARDEN_ANTHROPIC_API_KEY,
    model: trigger.model,
  });
  
  // 5. Render output
  const { review, summaryComment } = renderSkillReport(report, {
    reportOn: trigger.reportOn,
    failOn: trigger.failOn,
  });
}

​
API Reference

The library exports are organized into functional domains:

​
Core Execution

​
Configuration

​
Event Context

​
Trigger Matching

​
Output Rendering

​
Type System

Warden uses Zod schemas for runtime validation. All core types are exported: 
import type {
  // Core types
  EventContext,
  SkillReport,
  Finding,
  Severity,
  Location,
  
  // Configuration
  WardenConfig,
  SkillConfig,
  ResolvedTrigger,
  
  // Options
  SkillRunnerOptions,
  RenderOptions,
} from '@sentry/warden';
All schemas are also exported for custom validation: 
import { 
  SkillReportSchema,
  FindingSchema,
  EventContextSchema 
} from '@sentry/warden';

const parsed = SkillReportSchema.parse(data);

​
Error Handling

Warden exports custom error classes for different failure modes: 
import { 
  ConfigLoadError,
  SkillRunnerError,
  EventContextError,
  SkillLoaderError 
} from '@sentry/warden';

try {
  const config = loadWardenConfig(repoPath);
} catch (error) {
  if (error instanceof ConfigLoadError) {
    console.error('Invalid warden.toml:', error.message);
  }
}

​
Authentication Errors

API key issues are surfaced as SkillRunnerError with actionable guidance: 
try {
  await runSkill(skill, context, { apiKey });
} catch (error) {
  if (error instanceof SkillRunnerError && 
      error.message.includes('authentication')) {
    console.error('Set WARDEN_ANTHROPIC_API_KEY or run: claude login');
  }
}

​
ESM Only

Warden is published as an ESM-only package. Use import syntax: 
// ✅ Correct
import { runSkill } from '@sentry/warden';

// ❌ Wrong - CommonJS not supported
const { runSkill } = require('@sentry/warden');

​
TypeScript Configuration

For best results, enable strict mode in tsconfig.json: 
{
  "compilerOptions": {
    "strict": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2022"
  }
}

​
Next Steps

Run Skills

Execute Claude-powered analysis

Load Config

Parse warden.toml configuration

Build Context

Process GitHub webhooks

Render Output

Format findings for GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us