vdiff

Code Verification Layer

Know if your change is safe to merge in seconds. Deterministic checks + AI reasoning. No guesses.

vdiff analyzes git diffs and produces structured verification reports surfacing risks, detecting suspicious patterns, identifying validation gaps, and guiding human review.

Installation

npm install -g @4bk/vdiff
pip install graphifyy

vdiff requires Graphify (Python 3) to build the dependency graph for your codebase.

Cursor IDE (optional plugin)

Bundled Cursor plugin directory: plugins/cursor/ — rules, /vdiff skill, commands, optional stop-hook reminder. Local install:

ln -sf "$(pwd)/plugins/cursor" ~/.cursor/plugins/local/vdiff

Details: plugins/cursor/README.md. Uses Cursor Plugins and stop hooks.

Quick Start

# Navigate to your project
cd your-project

# Guided setup (API key, models, knowledge graph)
vdiff init

# Analyze your changes
vdiff -v

Run vdiff init from your project root so it can index your codebase and generate the knowledge graph.

See also vdiff models for curated default/high models per provider.

For agents and automation

Coding agents, CI, and scripts should use flags only (no interactive menus), JSON output, and --no-feedback. Set CI=1 or VDIFF_NON_INTERACTIVE=1 to skip the optional post-run feedback prompt in TTY environments.

• Stored reviews: use vdiff reviews list and vdiff reviews show <index> --format json — not bare vdiff reviews (that opens a TTY picker).
• Graph: prefer vdiff graph init when Graphify is available; --skip-graph on init is only for environments where Graphify cannot run yet.

Longer reference: AGENTS.md in this package (published on npm as @4bk/vdiff). Shorter hints also appear in vdiff --help and vdiff analyze --help.

Configuration

# Set provider explicitly
vdiff config set -g llm.provider anthropic

# Set default model (used for quick checks)
vdiff config set -g llm.model claude-haiku-4-5-20251001

# Set high-depth model (used with --thinking-level high)
vdiff config set -g llm.highModel claude-sonnet-4-6

# View current config
vdiff config list -g

# Show config file locations
vdiff config path

Configuration is stored in ~/.vdiff/config.json (global) and .vdiff/config.json (project-local, overrides global).

Config Schema

{
  "llm": {
    "provider": "anthropic",
    "apiKey": "sk-ant-...",
    "model": "claude-haiku-4-5-20251001",
    "highModel": "claude-sonnet-4-6"
  },
  "analysis": {
    "contextThreshold": 1.0
  }
}

Usage

Analyze Changes

# Smart default: staged if any, else unstaged
vdiff

# Staged changes only
vdiff --staged

# All changes (staged + unstaged)
vdiff --all

# Specific commit
vdiff --commit HEAD~1

# Branch diff (PR-style review)
vdiff --base main

# Piped diff
git diff | vdiff --stdin

Context and Depth

# Include full source of changed files
vdiff -f

# Deep analysis (better model + auto-includes full files)
vdiff --thinking-level high

# Verify changes against a spec, PRD, or task file
vdiff -s docs/spec.md

# Combine: deep analysis + spec verification
vdiff --thinking-level high -s docs/prd.md

# Only analyze files matching a pattern
vdiff -p "src/auth/**"

Output

# Verbose: show all sections and all findings
vdiff -v

# JSON output (for tooling / CI integration)
vdiff --format json

# Markdown output (for PR comments)
vdiff --format markdown

# Debug: show analysis progress and diagnostics
vdiff -d

Knowledge Graph

Provide cross-file dependency context for richer analysis.

# Build the knowledge graph (one-time)
vdiff graph init

# Check graph status
vdiff graph status

# Use a specific graph file
vdiff -g path/to/graph.json

# Skip graph context
vdiff --no-graph

Custom Rules

Define project-specific rules in .vdiff/rules/ as .md or .txt files:

mkdir -p .vdiff/rules

Example .vdiff/rules/billing.md:

- Any change to src/billing/ must include a migration file.
- Never remove rate limiting middleware from payment endpoints.
- Flag any hardcoded price or currency value.

Learned Rules

Save review decisions that persist across analyses:

# Add a global rule
vdiff rule add "API routes must validate request body"

# Add a scoped rule (only applies when matching files change)
vdiff rule add --scope "src/billing/**" "Never import from orders directly"

# List all rules
vdiff rule list

# Remove a rule
vdiff rule remove <n>

Git Hook

# Install pre-commit hook (blocks on high severity by default)
vdiff hook install

# Block on high + medium severity
vdiff hook install --block-on high,medium

# Informational only (no blocking)
vdiff hook install --block-on none

# Check hook status
vdiff hook status

# Remove the hook
vdiff hook remove

The hook runs vdiff --staged before each commit. By default, it blocks commits that introduce high-severity findings (security, data loss, auth bypass). Bypass with git commit --no-verify.

Configure the blocking threshold in .vdiff/config.json:

vdiff config set hook.blockOn '["high","medium"]'

IDE Integration

Install vdiff into your AI coding assistant:

# Install for a specific IDE
vdiff ide install cursor
vdiff ide install windsurf
vdiff ide install claude-code

# Install for all detected IDEs
vdiff ide install

# Check status
vdiff ide status

Review History

# Browse past reviews (interactive selector)
vdiff reviews

# List all stored reviews (non-interactive, agent/CI friendly)
vdiff reviews list

# Show a specific past review by index
vdiff reviews show <index>

CI / Exit Codes

# Exit non-zero when verdict is not_ready (default)
vdiff --base main

# Stricter: exit non-zero on caution OR not_ready
vdiff --base main --strict

Exit codes: 0 = ready or caution, 1 = not_ready. With --strict, caution also exits 1.

Output

vdiff separates what it knows from what it infers from what it can't verify:

| Section | What it shows | Mode | |---------|---------------|------| | Verdict | Merge readiness (ready/caution/not ready) + risk bar + actions | Always | | Change | Plain language description + file stats | Always | | Actions | Prioritized next steps (required/recommended/optional) | Verbose only | | Impact | Dependency graph impact level + affected dependents | When graph exists | | Structural Health | Quality signal + metric bars (Modularity, Acyclicity, Depth, Equality) | Verbose only | | Spec Alignment | Requirement coverage bar + status breakdown | When --spec used | | Findings | Risk inferences + missing evidence with severity, confidence, category | Always | | Review Delta | Resolved/reopened/open findings vs previous review | When prior review exists | | Focus | Prioritized files and lines to inspect first | Verbose only |

Example

──────────────────────────────────────────────────
  VDIFF ANALYSIS
──────────────────────────────────────────────────

VERDICT

  ⚠ Merge with caution
  → High impact: 19 files depend on changes

  Risk:  ●●○○○  Low · [Moderate] · High

  ! Fix: JWT secret read without fallback crashes server
  → Verify: Token refresh uses rotating keys per spec
  → Add tests for src/middleware/auth.ts

CHANGE

  Added JWT auth middleware with session validation
  and rate limiting on login endpoint.

  4 files +86 -12

IMPACT

  ●●●○○  Low · [Moderate] · High
  You changed 4 files. 7 other files depend on them.

  [shared]  src/middleware/auth.ts  → 5 dependents

FINDINGS

  1 high severity · 1 medium severity

  [HIGH] [verified]  src/middleware/auth.ts:34
  › JWT secret is read from process.env without
    fallback, server crashes on missing env var.

    Evidence:  validateToken() calls jwt.verify(token,
               process.env.JWT_SECRET) with no guard
    Confidence: ●●● [Strong]  ·  Category: [security]

  ... 1 more (use -v to expand)

──────────────────────────────────────────────────
  Verdict:  ⚠ Caution (High impact: 19 files depend on changes)
  Quality:  68 (Mod 71% · Acy 100% · Dep 58% · Eq 44%)
  Findings: 1 HIGH | 1 MEDIUM
  Changes:  4 files changed · 2 tests updated
  ↑18.2k · ↓2.1k · ~$0.07 · claude-haiku-4-5 · low · 3.1s
──────────────────────────────────────────────────

Use vdiff -v to expand all sections with full detail.

Analytics

vdiff can send anonymous usage to vdiff.app (opt-in by default during vdiff init for interactive setup; otherwise off until you enable it). This includes run counts, command name (analyze after each review, init after a successful setup), model/provider, finding counts, quality scores, source (cli vs cursor-plugin, from VDIFF_SOURCE or terminal heuristics—see below), and optional feedback from the “Was this useful?” prompt (-1 = not asked or skipped, including --no-feedback / JSON / non-TTY, 0 / 1 = down / up). No code, diffs, file contents, or API keys are sent.

The public API applies per-device daily and per-minute limits (e.g. separate caps for init vs analyze); see the web package README.md for current server behavior.

# Opt out of anonymous analytics
vdiff config set -g analytics.enabled false

# Opt back in
vdiff config set -g analytics.enabled true

You can also skip the post-analysis feedback prompt:

vdiff --no-feedback

Usage events are still sent when analytics are enabled; feedback is -1 when the prompt is skipped. To tag runs from Cursor integrations, set:

VDIFF_SOURCE=cursor-plugin vdiff --staged --format json --no-feedback

Otherwise vdiff uses source: cli, or cursor-plugin when TERM_PROGRAM contains cursor (override with VDIFF_SOURCE=cli if needed).

Local Data

vdiff stores all data locally:

• ~/.vdiff/config.json -- global configuration
• ~/.vdiff/device.json -- anonymous device identifier (for usage quota)
• .vdiff/config.json -- project-local config (overrides global)
• .vdiff/rules/*.md -- project-specific analysis rules
• .vdiff/rules/learned.md -- learned rules from review decisions
• .vdiff/reviews.json -- finding registry (review memory)
• .vdiff/reviews/results/*.json -- stored review results for vdiff reviews

LLM API calls use your own key (BYOK). Anonymous usage analytics are sent unless opted out (see above).

License

Apache License 2.0 by Árvore Sistemas. See LICENSE for details.