<div align="center"> <img src="site/visor.png" alt="Visor Logo" width="500" />

Visor — AI workflow engine for code review, assistants & automation

Orchestrate checks, MCP tools, and AI providers with YAML-driven pipelines. Runs as GitHub Action, CLI, Slack bot, Telegram bot, or HTTP API.

</div>

---

Visor is an open-source workflow engine that lets you define multi-step AI pipelines in YAML. Wire up shell commands, AI providers, MCP tools, HTTP calls, and custom scripts into dependency-aware DAGs — then run them from your terminal, CI, Slack, Telegram, Email, WhatsApp, Teams, or an HTTP endpoint.

What you get out of the box:

• YAML-driven pipelines — define checks, transforms, routing, and AI prompts in a single config file.
• 8 runtime modes — CLI, GitHub Action, Slack bot, Telegram bot, Email, WhatsApp, Teams, HTTP server — same config, any surface.
• 17 provider types — ai, command, script, mcp, utcp, http, claude-code, a2a, github, memory, workflow, and more.
• AI orchestration — multi-provider (Gemini, Claude, OpenAI, Bedrock), session reuse, MCP/UTCP tool calling, retry & fallback.
• Execution engine — dependency DAGs, parallel waves, forEach fan-out, conditional routing, failure auto-remediation.
• Built-in testing — YAML-native integration tests with fixtures, mocks, and assertions.

What do you want to build?

| Goal | Start here | Example | |------|-----------|---------| | Code review on PRs | Guide: Code Review Pipeline | quick-start-tags.yaml | | AI agent with tools | Guide: AI Agent | ai-custom-tools-simple.yaml | | Multi-step automation | Workflow Creation Guide | enhanced-config.yaml | | Chat assistant / Bot | Bot Integrations | teams-assistant.yaml | | Run shell commands + AI | Command Provider | ai-with-bash.yaml | | Connect MCP tools | MCP Provider | mcp-provider-example.yaml | | Call tools via UTCP | UTCP Provider | utcp-provider-example.yaml | | Add API integrations (TDD) | Guide: TDD Assistant Workflows | workable.tests.yaml |

First time? Run npx visor init to scaffold a working config, then npx visor to run it.

Table of Contents

• Quick Start
• AI Assistant Framework
• Runtime Modes
• PR Comment Commands
• Core Concepts
• Provider Types
• Orchestration
• AI & MCP
• GitHub Provider
• Templating & Transforms
• Suppressing Warnings
• Testing Framework
• SDK
• Configuration
• Observability
• Security
• Enterprise Policy Engine
• Further Reading
• Contributing
• License

Requirements: Node.js 18+ (CI runs Node 20).

🚀 Quick Start

Install & Run

# Install
npm i -D @probelabs/visor

# Scaffold a starter config (pick a template)
npx visor init                  # interactive picker
npx visor init code-review      # PR review pipeline
npx visor init agent            # AI agent with tools
npx visor init automation       # multi-step pipeline
npx visor init assistant        # chat assistant / Slack bot

# Run
npx visor                       # run all steps
npx visor --tags fast           # run steps tagged "fast"
npx visor validate              # check config for errors

Or one-off without installing: npx -y @probelabs/visor@latest --check all --output table

Minimal Config (.visor.yaml)

version: "1.0"
steps:
  security:
    type: ai
    prompt: "Identify security issues in changed files"
    tags: ["fast", "security"]

  run-tests:
    type: command
    exec: npm test
    depends_on: [security]

  notify:
    type: http
    method: POST
    url: https://hooks.slack.com/...
    body: '{ "text": "Tests {{ outputs[''run-tests''].status }}" }'
    depends_on: [run-tests]

As a GitHub Action

# .github/workflows/visor.yml
name: Visor
on:
  pull_request: { types: [opened, synchronize] }
  issues: { types: [opened] }
  issue_comment: { types: [created] }
permissions:
  contents: read
  pull-requests: write
  issues: write
  checks: write
jobs:
  visor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: probelabs/visor@v1
        env:
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}

Tip: Pin releases for stability with @v1. For bleeding-edge, use @nightly.

🤖 AI Assistant Framework

Visor ships with a built-in assistant framework — three composable workflows for building AI-powered assistants with skills, tools, and multi-repo code exploration. Import them with a single line:

version: "1.0"

imports:
  - visor://assistant.yaml

checks:
  chat:
    type: workflow
    workflow: assistant
    assume: ["true"]
    args:
      question: "{{ conversation.current.text }}"
      system_prompt: "You are a helpful engineering assistant."
      intents:
        - id: chat
          description: general Q&A or small talk
        - id: code_help
          description: questions about code or architecture
          default_skills: [code-explorer]
      skills:
        - id: code-explorer
          description: needs codebase exploration or code search
          tools:
            code-talk:
              workflow: code-talk
              inputs:
                projects:
                  - id: backend
                    repo: my-org/backend
                    description: Backend API service
          allowed_commands: ['git:log:*', 'git:diff:*']
    on_success:
      goto: chat

| Workflow | What it does | |----------|-------------| | assistant | Full AI assistant — intent routing, dynamic skill activation, tool orchestration, knowledge injection, bash command control | | code-talk | Multi-repo code exploration — routes questions to repos, checks out code, explores with tools, returns answers with file references and confidence scoring | | intent-router | Lightweight intent classification — picks intent, rewrites question, selects skills/tags |

The visor:// protocol resolves to bundled workflows shipped with the package — no network fetch needed.

Learn more: docs/assistant-workflows.md | Examples: code-talk-workflow · code-talk-as-tool · intent-router

🖥️ Runtime Modes

Visor runs the same YAML config across multiple surfaces:

| Mode | How to run | Best for | |------|-----------|----------| | CLI | visor --check all --output table | Local dev, CI pipelines | | GitHub Action | uses: probelabs/visor@v1 | PR reviews, issue triage, annotations | | Slack bot | visor --slack --config .visor.yaml | Team assistants, ChatOps | | Telegram bot | visor --telegram --config .visor.yaml | Personal assistants, group bots | | Email bot | visor --email --config .visor.yaml | Email assistants, threaded conversations | | WhatsApp bot | visor --whatsapp --config .visor.yaml | WhatsApp assistants, customer support | | Teams bot | visor --teams --config .visor.yaml | Enterprise assistants, team ChatOps | | HTTP server | http_server: { enabled: true, port: 8080 } | Webhooks, API integrations |

See Bot Integrations for a comparison of all bot transports.

Additional modes:

• TUI — interactive chat-style terminal UI: visor --tui
• SDK — programmatic Node.js API: import { runChecks } from '@probelabs/visor/sdk'
• Scheduler — cron-based execution with database-backed persistence

# CLI examples
visor --check all --output table
visor --tags fast,local --max-parallelism 5
visor --analyze-branch-diff                   # PR-style diff analysis
visor --event pr_updated                      # Simulate GitHub events
visor --tui --config ./workflow.yaml          # Interactive TUI
visor --debug-server --debug-port 3456        # Live web debugger
visor config snapshots                        # Config version history
visor validate                                # Validate config
visor test --progress compact                 # Run integration tests

Run modes: Default is CLI mode everywhere. For GitHub-specific behavior (comments, checks, annotations), run with --mode github-actions or set mode: github-actions in the Action. Force CLI mode inside Actions with VISOR_MODE=cli.

See docs/commands.md for the full CLI reference.

💬 PR Comment Commands

Trigger reviews and assistant actions via comments on PRs or issues:

/review                        # Re-run all checks
/review --check security       # Re-run specific check
/visor how does caching work?  # Ask the built-in assistant

Learn more: docs/commands.md

🧩 Core Concepts

| Concept | What