Behavior regression detection for critical systems

Getting Started with Vokt

Catch behavior changes before they reach production

Vokt shows how system behavior changes after every PR. Not just code diffs — behavior diffs. See when pricing rules shift, permissions change, or eligibility logic drifts, before it reaches production.

The Behavior Drift Problem

Every fast-moving team hits this wall. Your system grows. Logic spreads across services. No single engineer understands all downstream effects.

You ship a change:

✓ Tests pass
✓ CI green
✓ Code review approved

Then weeks later... pricing is wrong, refunds calculated differently, permissions shifted.

The Gap in Modern Stacks

Your tools detect syntax errors — types, tests, linting, performance, security. But nothing answers: "Did this change alter how the system behaves?"

This gap causes expensive production incidents

How Vokt Helps

Vokt compares what your system did before vs after — at the behavioral level. Detects logic changes, rule changes, workflow differences, and side-effect shifts.

Ship faster without silently changing how your system behaves

Prerequisites

• Package Manager - Homebrew (macOS/Linux) or Chocolatey (Windows)
• Vokt Account - Select a tier (FREE, PRO, or PREMIUM) and activate your license
• Git repository - Vokt integrates with your PR workflow

No API keys needed! Vokt uses server-based AI. Just activate your license and start detecting behavior changes.

Quick Start

Step 0: Register Your Email

Before using Vokt, register your email to activate your account.

1. Visit Vokt
2. Choose a tier (Free, Pro, or Premium)
3. Enter your email address to create your account
4. Your account is now active!

Step 1: Install Vokt

brew tap maneeshchaturvedi/vokt
brew install vokt

# Verify installation
vokt --version

Step 2: Initialize Vokt in Your Project

Navigate to your project and initialize Vokt:

cd your-project
vokt init

This creates the .vokt/ directory with configuration, specs storage, and file mappings.

Step 3: Generate Specs for Critical Files

Generate a behavioral specification for any file you want to protect:

# Generate a spec for a critical file
vokt generate src/payment/processor.js

# Or generate specs for multiple files
vokt generate src/pricing/*.js

Vokt analyzes the code and extracts its behavioral specification — what it does, its constraints, and its expected behaviors.

Step 4: Check for Behavior Drift

After making changes, check if behavior has drifted from the spec:

# Check a single file for drift
vokt drift check src/payment/processor.js

# Check all tracked files
vokt drift check

Example Output:

Checking src/payment/processor.js...

⚠️  DRIFT DETECTED

Behavior Change: Refund Eligibility
  - Before: Refunds allowed within 30 days of purchase
  + After:  Refunds allowed within 14 days of purchase

Behavior Change: Discount Scope
  - Before: Discount applies to all users with 3+ orders
  + After:  Discount applies to premium users only

✓ Preserved: Pricing calculation logic unchanged

You decide: Review the drift and either accept the behavior change (update the spec) or fix the unintended regression.

Step 5: Generate Tests from Specs

Automatically generate tests that verify the specified behavior:

vokt generate-tests src/payment/processor.js

Vokt creates comprehensive tests based on the behavioral specification, ensuring your code continues to behave as expected.

Why Teams Adopt Vokt

⚡Ship faster with confidence - Know that you're not breaking things you can't see

🔄Refactor without fear - Clean up code knowing behavior is preserved

⚠️Catch subtle regressions early - Before they reach production

🛡️Reduce incident risk - Especially in critical business logic

Tests tell you code works. Vokt tells you nothing important changed.

Vokt is the behavior validation layer — the next evolution after Version Control → Testing → CI/CD → Observability → Security.

Using with AI Coding Assistants

Vokt integrates with Claude Code and Cursor through MCP (Model Context Protocol). When you use AI assistants to make changes, Vokt automatically generates specs and detects drift.

The Workflow:

1.Open your codebase in Claude Code or Cursor
2.Ask your AI assistant to make a change (e.g., "Add EUR currency support")
3.Vokt automatically: Generates a spec (if none exists), detects drift, generates tests
4.Review the drift report before your AI assistant proceeds

AI tools increase code velocity — they also increase subtle regressions. Vokt is the layer that answers: "Are we still behaving the same?"

MCP Tools Reference

When using Claude Code or Cursor, these MCP tools are automatically called based on your actions:

Tool	When It's Used
vokt_modify_start	When you ask to analyze or prepare to modify a file
vokt_modify_complete	After you've made changes and want drift detection
vokt_create	When creating a new file spec-first
vokt_create_complete	After implementing a new file
vokt_review_queue	When checking pending reviews
generate_tests	When generating tests from specs

Conversation patterns: Say things like "I need to modify lib/hooks.js" to trigger vokt_modify_start, or "I've updated the code, here it is" to trigger vokt_modify_complete.

Real-Time IDE Feedback

Vokt includes an LSP server for real-time drift detection in your editor. Start it with:

vokt lsp serve

Features

•Real-time analysis — Drift detection as you type (debounced 500ms)
•Semantic diff — Function-level change detection (body vs signature)
•Intelligent caching — Parse cache, LLM cache for fast responses
•Incremental updates — Only re-analyzes what changed

Status Bar Indicators

$(sync~spin)Analysis in progress
$(check)Analysis complete
$(zap)Cached result (faster!)
$(error)Analysis error

VS Code Extension Commands

Command	Description
Vokt: Refresh Analysis	Force re-analyze current file
Vokt: Clear Cache	Clear all caches (parse, LLM, signature)
Vokt: Show Cache Stats	Display cache performance metrics
Vokt: Mark as Intended	Mark a drift as intentional
Vokt: Mark as Blocked	Mark a drift as blocked for later

Cache performance: First edit takes ~2-3s (LLM call). Same edit again takes ~50ms (cached). Look for the lightning bolt icon to know you're getting cached results.