VGuard

AI coding guardrails that actually enforce.

AI coding tools write code fast, but they also introduce security vulnerabilities, break project conventions, and push to protected branches. VGuard sits between the AI tool and your codebase, checking every proposed change before it happens. Bad changes get blocked with a clear explanation and a suggested fix. Good changes pass through without friction.

Quick Start

npm install -D @anthril/vguard
npx vguard init

Answer four questions and you have working guardrails. The init wizard detects your framework, asks which AI tools you use, and generates everything. See the full Getting Started guide.

Features

Runtime Enforcement — Claude Code hooks run before every tool call. VGuard inspects the proposed change, evaluates it against your rules, and blocks anything that violates them. The AI agent sees exactly what went wrong and how to fix it. Adapter docs →

Advisory Guidance — Cursor, Codex, and OpenCode don't support runtime hooks, so VGuard generates configuration files that teach the AI your project's rules before it starts writing. Agent setup →

Smart Detection — Edit rules only flag problems that are newly introduced. Pre-existing issues in the file are left alone so you can adopt guardrails incrementally without fixing every legacy violation first. Rules overview →

Rule Layers

Rules — 25 built-in

| Category | Count | Examples | Docs | | ------------ | ----: | --------------------------------------------------------------------- | -------------------------------------------------------- | | Security | 7 | branch-protection, secret-detection, prompt-injection, rls-required | security rules | | Quality | 11 | import-aliases, naming-conventions, hallucination-guard, dead-exports | quality rules | | Workflow | 7 | commit-conventions, pr-reminder, migration-safety, changelog-reminder | workflow rules |

Presets — 14 ecosystem presets

nextjs-15 · react-19 · typescript-strict · supabase · tailwind · django · fastapi · laravel · wordpress · react-native · astro · sveltekit · python-strict · go

Browse all presets →

Agent Support

Documentation

| Section | Description | | ----------------------------------------------------------- | --------------------------------------------- | | Getting Started | Install, init wizard, first run | | Configuration | vguard.config.ts reference | | CLI | init, add, remove, generate, doctor | | Rules | All built-in rules with examples | | Presets | Framework-specific rule bundles | | Agent Setup | Per-agent adapter configuration | | Custom Rules | Write your own guardrails | | Troubleshooting | Common issues and fixes |

Exit codes

VGuard follows the BSD sysexits.h conventions so CI scripts can branch on specific failure modes. The mapping is stable across the major version and lives in src/cli/exit-codes.ts.

| Code | Name | When | | ----- | --------------- | --------------------------------------------------------------------------------------------- | | 0 | OK | Success. | | 1 | LINT_BLOCKING | vguard lint found one or more block-severity issues. | | 2 | USAGE | Unknown flag, missing required argument, invalid --format choice, --check + --apply. | | 65 | DATA_ERR | Config file loaded but failed validation (malformed JSON / zod parse error). | | 66 | NO_INPUT | Expected config not found (e.g. any command needing vguard.config.ts before vguard init). | | 69 | UNAVAILABLE | Cloud API or network dependency unreachable. | | 70 | SOFTWARE | Unexpected internal error. --debug reveals the stack trace. | | 77 | NO_PERM | Not logged in, 401/403 from Cloud, missing API key. | | 78 | CONFIG | vguard doctor ran all checks and at least one failed (or warned with --strict). | | 130 | SIGINT | Ctrl+C — interactive prompts and long-running commands both honour this. |

Example CI gate:

vguard doctor --strict
case $? in
  0)  echo "healthy" ;;
  66) echo "run 'vguard init' first" ;;
  78) echo "config or hooks broken - blocking deploy"; exit 1 ;;
  *)  exit 1 ;;
esac

Terminal behaviour

VGuard plays nicely with pipes, CI, and accessibility tooling out of the box:

| Variable / flag | Effect | | ------------------------------ | -------------------------------------------------------------------------------------------------------------- | | NO_COLOR=1 (env) | Disable all ANSI colour output. Follows the no-color.org standard. | | --no-color | Same as NO_COLOR=1 for a single invocation. | | --ascii | Replace Unicode glyphs (●, ✓, ✗) with ASCII equivalents (*, [ok], [fail]). Useful on LANG=C. | | -q / --quiet | Suppress banners, progress spinners, and summaries. Machine output on stdout is unaffected. | | --verbose | Emit extra diagnostic detail on stderr. | | --debug (or DEBUG=vguard*) | Show full stack traces on error instead of the friendly one-line message. | | CI=true (env, auto-detected) | Disables interactive prompts; commands fall back to defaults or --yes-style flags. | | stdout not a TTY | Auto-disables colour, spinners, and the vguard no-args setup hint — safe for vguard cmd \| jq . pipelines. |

vguard already auto-detects non-TTY stdout, so you rarely need to set any of these manually.

VGuard Cloud

VGuard Cloud gives your team a dashboard for AI coding activity — which rules fire most, who's triggering blocks, and how conventions drift over time. Set up drift alerts, connect webhooks, and export analytics. Free tier available for small teams.

Cloud docs → · Sign up →

Sponsors

This project is maintained by Anthril and funded by our sponsors.

Become a sponsor →

Community

• GitHub Discussions
• Contributing
• Code of Conduct
• Security Policy
• Changelog

License

Apache 2.0 — Anthril