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.
npm install -g @4bk/vdiff
pip install graphifyyvdiff requires Graphify (Python 3) to build the dependency graph for your codebase.
# Navigate to your project
cd your-project
# Guided setup (API key, models, knowledge graph)
vdiff init
# Analyze your changes
vdiff -vRun 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.
# 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 pathConfiguration is stored in ~/.vdiff/config.json (global) and .vdiff/config.json (project-local, overrides global).
{
"llm": {
"provider": "anthropic",
"apiKey": "sk-ant-...",
"model": "claude-haiku-4-5-20251001",
"highModel": "claude-sonnet-4-6"
},
"analysis": {
"contextThreshold": 1.0
}
}# 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# 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/**"# 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 -dProvide 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-graphDefine project-specific rules in .vdiff/rules/ as .md or .txt files:
mkdir -p .vdiff/rulesExample .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.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># 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 removeThe 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"]'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# 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># Exit non-zero when verdict is not_ready (default)
vdiff --base main
# Stricter: exit non-zero on caution OR not_ready
vdiff --base main --strictExit codes: 0 = ready or caution, 1 = not_ready. With --strict, caution also exits 1.
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 |
──────────────────────────────────────────────────
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.
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, and optional feedback from the “Was this useful?” prompt (-1 = not asked or skipped, 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 trueYou can also skip the post-analysis feedback prompt:
vdiff --no-feedbackvdiff 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 forvdiff reviews
LLM API calls use your own key (BYOK). Anonymous usage analytics are sent unless opted out (see above).
Apache License 2.0 by Árvore Sistemas. See LICENSE for details.