This directory contains SDK examples (programmatic usage) and configuration examples (YAML files).

Use Visor from Node.js without shelling out.

# Build SDK first
npm run build:sdk

# Basic SDK examples
node examples/sdk-basic.mjs           # Minimal (5 lines)
node examples/sdk-cjs.cjs             # CommonJS
node examples/sdk-manual-config.mjs   # Manual config
node examples/sdk-comprehensive.mjs   # Complex with dependencies

# TypeScript (full type safety with SDK types)
npx tsc examples/sdk-typescript.ts --module esnext --target es2022 --moduleResolution bundler --esModuleInterop --skipLibCheck && node examples/sdk-typescript.js

Interactive calculator demonstrating human-in-the-loop workflows:

# Interactive calculator with table output
bun examples/calculator-sdk-real.ts

# Calculator with JSON output (programmatic processing)
bun examples/calculator-sdk-json.ts

# Fully automated calculator (for testing/automation)
bun examples/calculator-sdk-automated.ts
bun examples/calculator-sdk-automated.ts 10 5 +  # With args

# YAML config version
./dist/index.js --config examples/calculator-config.yaml --message "10" --check get-number1

Features demonstrated:

• ✅ Human input via human-input check type
• ✅ Memory provider for state management
• ✅ JavaScript execution in memory provider
• ✅ Dependency chains with fail_if validation
• ✅ JSON output for programmatic processing
• ✅ Custom visualization in SDK scripts
• ✅ Suppressing stdout/stderr for clean JSON responses

See docs/sdk.md for full SDK documentation.

Example configurations demonstrating various Visor features and use cases.

• quick-start-tags.yaml - Simple configuration showing basic tag usage
• visor-with-tags.yaml - Comprehensive configuration with all tag features
• enhanced-config.yaml - Enhanced configuration with advanced features

• routing-basic.yaml - Failure routing with retry + goto ancestor
• routing-on-success.yaml - on_success post-steps + single jump-back
• routing-foreach.yaml - forEach remediation with run + retry
• routing-dynamic-js.yaml - Dynamic routing via goto_js/run_js
• routing-goto-event.yaml - Goto routing with event handling

• if-conditions.yaml - Conditional execution with if statements
• for-loop-example.yaml - Loop iteration patterns
• forEach-example.yaml - ForEach iteration over collections
• transform-example.yaml - Data transformation between steps

• ai-custom-tools-example.yaml - AI with custom shell-based tools via ephemeral MCP servers
• ai-custom-tools-simple.yaml - Simplified AI custom tools example
• api-tools-ai-example.yaml - AI check using reusable OpenAPI-backed type: api tool bundles (includes embedded tests)
• ai-retry-fallback-config.yaml - AI with retry and fallback providers
• ai-with-bash.yaml - AI check combined with bash command execution
• ai-with-mcp.yaml - AI check with MCP tool integration
• bedrock-config.yaml - AWS Bedrock AI provider configuration
• claude-code-config.yaml - Claude Code SDK integration with MCP tools
• fact-validator.yaml - AI-based fact validation workflow

• mcp-provider-example.yaml - MCP provider with stdio/SSE/HTTP transports
• custom-tools-example.yaml - Custom tool definitions
• api-tools-library.yaml - Reusable OpenAPI API tool bundle definitions (type: api)
• api-tools-mcp-example.yaml - MCP checks calling OpenAPI-generated operations from reusable API bundle (includes embedded tests)
• api-tools-inline-overlay-example.yaml - Inline/file OpenAPI overlay example with reusable API tools (includes embedded tests)
• tools-library.yaml - Reusable tool library (git, docker, npm, testing, code quality tools)
• reusable-tools.yaml - Patterns for reusable tool definitions
• project-with-tools.yaml - Project configuration with integrated tools

• memory-counter.yaml - Basic memory counter implementation
• memory-error-collection.yaml - Collecting errors in memory across steps
• memory-exec-js.yaml - JavaScript execution within memory provider
• memory-namespace-isolation.yaml - Memory namespace isolation between workflows
• memory-retry-counter.yaml - Retry logic with memory-based counter tracking
• memory-state-machine.yaml - State machine implementation using memory

• human-input-example.yaml - Interactive human-in-the-loop patterns
• basic-human-input.yaml - Basic human input workflow
• calculator-config.yaml - Interactive calculator with memory and validation

• http-integration-config.yaml - HTTP API integration patterns
• https-server-config.yaml - HTTPS server configuration
• webhook-pipeline-config.yaml - Multi-pipeline webhook system (GitHub, JIRA integration)
• cron-webhook-config.yaml - Scheduled cron triggers with webhooks

• git-checkout-basic.yaml - Basic git checkout operations
• git-checkout-compare.yaml - Git checkout with comparison workflows
• git-checkout-cross-repo.yaml - Cross-repository git operations

• fail-if-simple.yaml - Simple fail_if conditions
• failure-conditions-basic.yaml - Basic failure condition patterns
• failure-conditions-advanced.yaml - Advanced failure handling with complex conditions
• failure-conditions-github-style.yaml - GitHub-style failure conditions
• failure-conditions-migration.yaml - Migration patterns for failure conditions

• sandbox-basic.yaml - Basic Docker sandbox with image mode
• sandbox-cache.yaml - Sandbox with cache volume mounts
• sandbox-dockerfile-inline.yaml - Sandbox with inline Dockerfile
• sandbox-env-passthrough.yaml - Sandbox environment variable passthrough
• sandbox-multi-env.yaml - Multiple sandbox environments per check
• sandbox-read-only.yaml - Read-only sandbox with network isolation

• enterprise-policy/ - OPA policy engine with role-based access control (Enterprise Edition -- requires license, contact hello@probelabs.com)

• jira-simple-example.yaml - Simple JIRA integration
• jira-single-issue-workflow.yaml - Single JIRA issue workflow
• jira-workflow-mcp.yaml - JIRA workflow with MCP tools
• slack-simple-chat.yaml - Slack bot simple chat integration

• session-reuse-config.yaml - Session reuse configuration
• session-reuse-self.yaml - Self-referencing session reuse patterns
• on-init-import-demo.yaml - On-init hooks with imports
• reusable-workflows.yaml - Reusable workflow patterns

• outputs-raw-basic.yaml - Raw output formatting

• github-workflow-with-tags.yml - Progressive code review workflow using tags

• environments/visor.base.yaml - Base configuration with all check definitions
• environments/visor.dev.yaml - Development environment (fast, local checks)
• environments/visor.staging.yaml - Staging environment (balanced checks)
• environments/visor.prod.yaml - Production environment (comprehensive validation)

• workflows/calculator-workflow.yaml - Reusable calculator workflow with inputs/outputs
• workflows/code-quality.yaml - Code quality workflow (linting, complexity, formatting)
• workflows/quick-pr-check.yaml - Quick PR validation workflow
• workflows/workflow-composition-example.yaml - Workflow composition and state isolation demo

Start with the simple configuration:

# Copy the quick-start example
cp examples/quick-start-tags.yaml .visor.yaml

# Run local checks
visor --tags local,fast

# Run comprehensive checks
visor --tags remote,comprehensive

Use different configurations for different environments:

# Development
visor --config examples/environments/visor.dev.yaml

# Staging
visor --config examples/environments/visor.staging.yaml

# Production
visor --config examples/environments/visor.prod.yaml

Copy the workflow to your repository:

cp examples/github-workflow-with-tags.yml .github/workflows/code-review.yml

• local - Runs on developer machines
• remote - Runs in CI/CD
• dev - Development environment
• staging - Staging environment
• prod - Production environment

• fast - Completes in < 30 seconds
• slow - Takes > 30 seconds
• comprehensive - Thorough but time-consuming

• security - Security-related checks
• performance - Performance analysis
• quality - Code quality and style
• testing - Test-related checks
• documentation - Documentation checks

• critical - Must pass for deployment
• optional - Nice to have but not blocking
• experimental - Beta features

# Fast security checks for local development
visor --tags local,fast,security

# All critical checks for production
visor --tags prod,critical

# Comprehensive review excluding experimental
visor --tags comprehensive --exclude-tags experimental

# Just the essentials
visor --tags critical,fast

tag_filter:
  include: ["local", "fast"]
  exclude: ["slow", "experimental"]

• Goal: Quick feedback during development
• Runtime: < 1 minute
• Use Case: Pre-commit hooks, local testing

tag_filter:
  include: ["remote", "critical"]
  exclude: ["experimental"]

• Goal: Validate changes before merge
• Runtime: 2-5 minutes
• Use Case: GitHub Actions on PR

tag_filter:
  include: ["staging", "comprehensive"]
  exclude: ["experimental", "optional"]

• Goal: Thorough validation before production
• Runtime: 5-10 minutes
• Use Case: Staging deployment pipeline

tag_filter:
  include: ["prod", "critical", "comprehensive"]
  exclude: ["experimental"]

• Goal: Maximum confidence for production
• Runtime: 10+ minutes
• Use Case: Production deployment gate

Start with fast checks and progressively run more comprehensive ones:

# Stage 1: Critical issues (fail fast)
visor --tags critical,fast --fail-fast

# Stage 2: Security scan (if stage 1 passes)
visor --tags security --exclude-tags fast

# Stage 3: Comprehensive review (if all pass)
visor --tags comprehensive --exclude-tags security,critical

Run checks based on file changes:

steps:
  frontend-checks:
    tags: ["frontend", "conditional"]
    on: [pr_opened]
    if: "filesChanged.some(f => f.endsWith('.tsx'))"

  backend-checks:
    tags: ["backend", "conditional"]
    on: [pr_opened]
    if: "filesChanged.some(f => f.endsWith('.py'))"

steps:
  quick-scan:
    tags: ["local", "fast"]

  deep-scan:
    tags: ["remote", "slow"]
    depends_on: [quick-scan]  # Only if quick-scan is included

  report:
    tags: ["reporting"]
    depends_on: [quick-scan, deep-scan]  # Uses whatever ran

1. Start Simple: Begin with local/remote or fast/slow
2. Be Consistent: Use the same tags across all projects
3. Document Tags: Maintain a tag glossary in your docs
4. Review Regularly: Audit and update tags as needs change
5. Measure Impact: Track execution times and adjust tags accordingly

• Use visor --help to see all available options
• Combine --tags and --exclude-tags for precise control
• Set default tag_filter in config to avoid repetition
• Use environment-specific configs with extends for DRY principles
• Test tag filters with --debug to see which checks run

# Run Slack bot (requires SLACK_BOT_TOKEN, SLACK_APP_TOKEN env vars)
visor --config examples/slack-simple-chat.yaml

# Simple JIRA workflow
visor --config examples/jira-simple-example.yaml

# JIRA with MCP tools
visor --config examples/jira-workflow-mcp.yaml

# Multi-pipeline webhook server
visor --config examples/webhook-pipeline-config.yaml

# Cron-triggered webhooks
visor --config examples/cron-webhook-config.yaml

# Basic memory counter
visor --config examples/memory-counter.yaml

# State machine with memory
visor --config examples/memory-state-machine.yaml

# Retry logic with counter
visor --config examples/memory-retry-counter.yaml

# AI with custom tools (ephemeral MCP servers)
visor --config examples/ai-custom-tools-example.yaml

# AI with bash execution
visor --config examples/ai-with-bash.yaml

# AWS Bedrock provider
visor --config examples/bedrock-config.yaml --provider bedrock

# Claude Code SDK integration
visor --config examples/claude-code-config.yaml

# Basic Docker sandbox
visor --config examples/sandbox-basic.yaml

# Sandbox with cache volumes
visor --config examples/sandbox-cache.yaml

# Inline Dockerfile sandbox
visor --config examples/sandbox-dockerfile-inline.yaml

# Environment variable passthrough
visor --config examples/sandbox-env-passthrough.yaml

# Multiple sandbox environments
visor --config examples/sandbox-multi-env.yaml

# Read-only sandbox with network isolation
visor --config examples/sandbox-read-only.yaml

# MCP provider with different transports
visor --config examples/mcp-provider-example.yaml

# Custom tools
visor --config examples/custom-tools-example.yaml

Import and compose workflows:

# Use the calculator workflow
visor --config examples/workflows/calculator-workflow.yaml --input "num1=10" --input "num2=5" --input "operation=add"

# Code quality workflow
visor --config examples/workflows/code-quality.yaml --input "language=typescript"

# Quick PR check
visor --config examples/workflows/quick-pr-check.yaml --input "pr_type=feature"

# Workflow composition example (imports calculator-workflow)
visor --config examples/workflows/workflow-composition-example.yaml

Enterprise Edition feature. Requires a Visor EE license. Contact hello@probelabs.com for licensing.

Role-based access control for checks, MCP tools, and AI capabilities using OPA (Open Policy Agent) policies:

# Install EE build
npm install @probelabs/visor@ee

# Set license
export VISOR_LICENSE="<your-jwt-token>"

# Run with policy enforcement
visor --config examples/enterprise-policy/visor.yaml

See examples/enterprise-policy/README.md for full documentation, configuration reference, and Rego policy examples.

• Main README - Complete Visor documentation
• Configuration Guide - Detailed config options
• GitHub Actions Guide - CI/CD integration

Interactive workflows with human-in-the-loop:

# Basic human input patterns
visor --config examples/human-input-example.yaml

# Interactive calculator (demonstrates memory + JS + human input)
visor --config examples/calculator-config.yaml

# Run with inline message
visor --config examples/human-input-example.yaml --check approval-gate --message "yes"

# Run with file input (auto-detected)
echo "yes" > approval.txt
visor --config examples/human-input-example.yaml --check approval-gate --message approval.txt

# Run with piped input
echo "yes" | visor --config examples/human-input-example.yaml --check approval-gate

Calculator Example: The calculator demonstrates a complete workflow:

1. Prompts for first number
2. Prompts for second number
3. Prompts for operation (+, -, *, /)
4. Stores values in memory
5. Calculates result using JavaScript
6. Displays formatted result

SDK Usage:

Two SDK examples are provided:

1. calculator-sdk-real.ts - Complete, runnable SDK example:

   • Real imports from Visor SDK
   • Config defined inline (no YAML needed)
   • Custom readline-based input hook
   • Full CheckExecutionEngine usage
   • Works in interactive or automated mode

   # Interactive mode
   ts-node examples/calculator-sdk-real.ts
   
   # Automated mode (for testing)
   ts-node examples/calculator-sdk-real.ts 42 7 +

2. calculator-sdk-example.ts - Documentation/template example:

   • Shows the structure and patterns
   • Includes comments and explanations
   • Generates YAML config for CLI usage

SDK Pattern:

import { HumanInputCheckProvider } from '../src/providers/human-input-check-provider';
import { CheckExecutionEngine } from '../src/check-execution-engine';
import { VisorConfig } from '../src/types/config';

// Define config inline
const config: VisorConfig = {
  version: "1.0",
  checks: {
    "my-check": {
      type: "human-input",
      prompt: "Enter value:"
    }
  },
  output: { pr_comment: { format: "markdown", group_by: "check", collapse: false } }
};

// Set custom hook
HumanInputCheckProvider.setHooks({
  onHumanInput: async (request) => {
    return await myCustomHandler(request);
  }
});

// Run checks
const engine = new CheckExecutionEngine();
const results = await engine.executeChecks(prInfo, config, Object.keys(config.checks));

Run the examples directly from the repo root:

# Basic retry + goto ancestor
npx -y @probelabs/visor@latest --config examples/routing-basic.yaml --output table

# on_success: run notify and jump back once to re-run unit-tests
npx -y @probelabs/visor@latest --config examples/routing-on-success.yaml --output table

# forEach remediation: mark missing items then retry
npx -y @probelabs/visor@latest --config examples/routing-foreach.yaml --output table

# Dynamic routing with *_js hooks
npx -y @probelabs/visor@latest --config examples/routing-dynamic-js.yaml --output table

Notes:

• These examples create small temporary files in the repo (prefixed with .visor_demo_). Run git clean -fdx or delete the files manually to reset.
• The routing block supports max_loops and default retry policies; step-level settings override defaults.
• See docs/failure-routing-rfc.md for full semantics.