vettd

Your code has been vettd.

Quality gates for AI-generated code. A CLI tool that helps citizen developers prove their code meets production standards.

Dave from HR built an app with Claude Code. It works. But is it good? Is it secure? Will it survive production? Vettd answers that question in seconds.

npx vettd .

No account. No config. No API key required.

What you get

▸ Scanning project... found 47 files (12 source, 3 test, 32 other)
▸ Running static checks...
  ✓ Static analysis (3 warnings)
▸ Running deep analysis (Claude)...
  ✓ Deep analysis (1 critical, 2 warnings)

────────────────────────────────────────
Overall Grade: B (7.2/10)
────────────────────────────────────────
Security        6/10  Reliability     7/10  Maintainability 8/10
Test Cov.       5/10  Dependencies    9/10  Architecture    7/10

⚠ CRITICAL (1)
  SQL injection in src/api/users.ts:42
  User input interpolated directly into SQL query.
  → Use parameterised queries.

⚡ WARNINGS (5)
  • [email protected] has known CVE (package.json)
  • No error boundary around API calls (src/app/dashboard.tsx:18)
  • Function exceeds complexity threshold (src/lib/process.ts:89)
  • Business logic in route handler (src/api/orders.ts:15)
  • No tests for 3 source files (src/lib/)

Full report: .vettd/report.json | HTML: vettd --html

How it works

Vettd runs two layers of analysis:

Static layer (always runs, no API key needed):

• Dependency audit via npm audit
• Secret detection (AWS keys, GitHub tokens, API keys, private keys)
• Complexity analysis (file length, function length, cyclomatic complexity)
• Test coverage check (test-to-source ratio, untested files)
• Baseline checks (missing .gitignore, no error handling, no tsconfig)

LLM layer (optional, requires Claude access via Anthropic API, AWS Bedrock, or Google Vertex AI):

• Security review — injection risks, auth bypasses, data exposure
• Architecture review — separation of concerns, coupling, patterns
• Reliability review — missing error handling, race conditions, resource leaks

Install

# Run directly (no install)
npx vettd .

# Or install globally
npm install -g vettd
vettd .

New to the command line? See the Getting Started guide for step-by-step instructions including how to install Node.js.

Commands

Run vettd guide for a quick-reference of all commands, or vettd --help for CLI usage.

vettd .                        # Full analysis (static + LLM if API key set)
vettd . --quick                # Static checks only (no API key needed)
vettd . --html                 # Generate HTML report, open in browser
vettd . --ci --min-grade C     # CI mode: exit 1 if grade below threshold
vettd init                     # Set up .vettd/config.json
vettd claudecode               # Add quality gate to CLAUDE.md for Claude Code
vettd guide                    # Show quick-start guide and all commands

# Manager commands (multi-repo oversight)
vettd manager init             # Verify gh auth, create ~/.vettd/manager.json
vettd manager watch owner/repo # Add repo to watch list
vettd manager unwatch owner/repo # Remove repo from watch list
vettd manager list             # Show watched repos
vettd manager report           # Fetch artifacts, show multi-repo quality table
vettd manager report --html    # Generate HTML dashboard
vettd manager report --trend   # Include score history from recent runs
vettd manager policy --min-grade B --require security=7 --max-criticals 0

Progressive value

Each step is independently valuable. No step requires the next.

| Step | What you do | What you get | |------|------------|--------------| | 1 | npx vettd . | Instant quality report (static checks) | | 2 | Connect Claude (API key, Bedrock, or Vertex) | Deep analysis (security, architecture, reliability) | | 3 | vettd claudecode | Claude Code automatically fixes what Vettd flags | | 4 | Add --ci to your pipeline | Automated quality gate that blocks bad code | | 5 | vettd manager init | Multi-repo dashboard for team leads |

CI / GitHub Actions

Using the action

# .github/workflows/quality.yml
name: Quality Gate
on: [push, pull_request]

jobs:
  vettd:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: andrevs/vettd/action@master
        with:
          min-grade: "C"

For deeper analysis, add your Anthropic key:

      - uses: andrevs/vettd/action@master
        with:
          min-grade: "C"
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Using npx directly

      - run: npx vettd . --ci --min-grade C

The job fails if the project scores below the threshold. Reports are automatically uploaded as artifacts.

Scoring

Vettd scores 6 quality dimensions from 0-10:

| Dimension | Weight | What it checks | |-----------|--------|---------------| | Security | 2.0x | Vulnerabilities, secrets, injection risks | | Reliability | 1.5x | Error handling, edge cases, failure modes | | Test Coverage | 1.5x | Test files exist and are meaningful | | Dependencies | 1.0x | Outdated packages, CVEs, license issues | | Maintainability | 1.0x | Code clarity, complexity, function length | | Architecture | 1.0x | Separation of concerns, coupling, patterns |

Overall grade is a weighted average:

| Grade | Score | Meaning | |-------|-------|---------| | A | 9-10 | Production-ready, senior-engineer quality | | B | 7-8.9 | Good, minor improvements suggested | | C | 5-6.9 | Functional but needs work | | D | 3-4.9 | Significant issues | | F | 0-2.9 | Critical problems, do not ship |

Manager (multi-repo oversight)

For team leads who need visibility across multiple repos. Requires the GitHub CLI (gh) and repos running the Vettd GitHub Action.

# One-time setup
vettd manager init
vettd manager watch acme/frontend
vettd manager watch acme/api
vettd manager policy --min-grade B --require security=7

# See how your team is doing
vettd manager report

  vettd manager  ·  3 repos watched

  Policy: min grade B | security >= 7

  Repository          Grade  Score  Sec   Rel   Main  Status
  ─────────────────────────────────────────────────────────────
  acme/frontend         B    7.2    8.1   7.0   6.5   PASS
  acme/api              D    3.8    2.1   5.0   4.2   FAIL ▸ grade below B
  acme/shared-lib       —     —      —     —     —    NO DATA
  ─────────────────────────────────────────────────────────────
  1 passing · 1 failing · 1 no data | Avg: 5.5/10

vettd manager report exits with code 1 if any repo fails policy, so you can use it in CI for org-wide enforcement. Add --html for a dashboard or --trend for score history.

Config

Run vettd init to create .vettd/config.json:

{
  "provider": "anthropic",
  "anthropic_api_key_env": "ANTHROPIC_API_KEY",
  "min_grade": "C",
  "weights": {
    "security": 2.0,
    "reliability": 1.5,
    "test_coverage": 1.5,
    "dependencies": 1.0,
    "maintainability": 1.0,
    "architecture": 1.0
  },
  "exclude": [],
  "model": "claude-sonnet-4-20250514",
  "schema_version": 1
}

The config is safe to commit — it stores the env var name, not the key itself.

Enterprise providers

For organisations using AWS Bedrock or Google Vertex AI, set the provider field:

{ "provider": "bedrock", "aws_region": "us-east-1" }

{ "provider": "vertex", "gcp_project_id": "my-project", "gcp_region": "us-east5" }

Bedrock uses your AWS credential chain (IAM roles, SSO, env vars). Vertex uses Google Application Default Credentials. No Anthropic API key needed for either.

See the Getting Started guide for full setup instructions.

Who is this for?

Dave (citizen developer) — Built something with AI, wants to know if it's production-ready before showing anyone.

Dave's manager — Needs visibility into what citizen developers are shipping. Run vettd manager report to see quality status across all watched repos, enforce org-wide policies, and track trends. Can also require --ci as a merge gate.

Compliance / Security — Needs an audit trail. Every scan produces a JSON report with timestamped findings.

Language support

Currently supports JavaScript/TypeScript projects. More languages coming.

License

MIT