vibecheck

AI code hallucination detector -- find phantom deps, fake APIs, and ghost routes.

Quick Start

# Scan your project (no install needed)
npx vibecheck scan .

# Or install globally
npm install -g vibecheck
vibecheck scan .

Commands

vibecheck scan

Scan a file or directory for all findings.

vibecheck scan .
vibecheck scan src/
vibecheck scan src/api.ts

Flags:

| Flag | Default | Description | |------|---------|-------------| | --json | — | Output findings as JSON | | --no-color | — | Disable ANSI color output | | --threshold <n> | 75 | Minimum confidence to include a finding (0–100) |

Example output:

  VibeCheck Scan
  3 files · 5 findings · 412ms

  ──────────────────────────────────────────────────────

  src/lib/payments.ts
  ──────────────────────────────────────────────────────
  ✗  CRIT  CRED001  line 12   Stripe live secret key hardcoded
     Move to process.env.STRIPE_SECRET_KEY

  ✗  HIGH  SEC001   line 34   SQL injection: template literal in query
     Use parameterized queries

  src/api/routes.ts
  ──────────────────────────────────────────────────────
  ✗  CRIT  GRT001   line 8    Ghost route: /api/payments/confirm has no handler
     Closest match: /api/payment/confirm (did you mean this?)

  ──────────────────────────────────────────────────────
  5 findings  ·  2 critical  ·  2 high  ·  1 medium

JSON output (--json):

{
  "findings": [
    {
      "id": "...",
      "engine": "credentials",
      "severity": "critical",
      "ruleId": "CRED001",
      "file": "src/lib/payments.ts",
      "line": 12,
      "message": "Stripe live secret key hardcoded",
      "evidence": "const key = 'sk_live_abc123...'",
      "suggestion": "Move to process.env.STRIPE_SECRET_KEY",
      "confidence": 0.99
    }
  ],
  "meta": {
    "filesScanned": 3,
    "totalFindings": 5,
    "durationMs": 412
  }
}

vibecheck score

Compute and display the trust score for a file or directory.

vibecheck score .
vibecheck score src/ --json

Example output:

  VibeCheck Trust Score
  3 files · 5 findings · 412ms

  [██████████████████░░░░░░░░░░░░]  72/100 (C)

  Verdict    REVIEW
  Mixed reliability. Manual review recommended before shipping.

  Findings   2 critical · 2 high · 1 other

  ────────────────────────────────────────────────────────

  Dimensions

    API Integrity         [████████████████░░░░]  80
    Dependency Safety     [██████████████░░░░░░]  70
    Env Coverage          [████████████████████]  100
    Contract Health       [████████████░░░░░░░░]  60

  ────────────────────────────────────────────────────────

  Score Reducers (3 total)

     -15  1 critical Hardcoded Secrets finding — blocks shipping (CRED001)
      -8  1 high Security Vulnerabilities finding (SEC001)
      -5  1 high Ghost Routes finding (GRT001)

  ────────────────────────────────────────────────────────
  ▲ Run vibecheck scan to review flagged issues before shipping.

Flags:

| Flag | Default | Description | |------|---------|-------------| | --json | — | Output score as JSON | | --no-color | — | Disable color |

vibecheck guard

Scan and exit with code 1 if the trust score is below threshold or critical findings exist. Designed for CI pipelines.

vibecheck guard .
vibecheck guard . --threshold 80
vibecheck guard . --fail-on critical
vibecheck guard . --fail-on none   # Never fail, just report

Flags:

| Flag | Default | Description | |------|---------|-------------| | --threshold <n> | 70 | Minimum score to pass | | --fail-on <level> | critical | Fail on: critical, high, any, none | | --json | — | Output report as JSON |

Exit codes:

| Code | Meaning | |------|---------| | 0 | Passed — score above threshold, no blocking findings | | 1 | Failed — score below threshold or critical finding found | | 2 | Error — invalid arguments or scan error |

Example CI usage:

- name: VibeCheck Guard
  run: npx vibecheck guard . --threshold 70

vibecheck roast

Scan and deliver a brutal, opinionated summary of how AI-generated the code looks.

vibecheck roast .
vibecheck roast src/

Example output:

  VibeCheck Roast
  ──────────────────────────────────────────────────────────

  Let me be direct: this codebase has AI fingerprints all over it.

  The Worst Offender
  src/lib/payments.ts — 3 findings, trust score 42

  Stats
  ┌─────────────────────────────────┐
  │  Trust Score     42/100   F    │
  │  Hallucinations  3             │
  │  Phantom Deps    1             │
  │  Hardcoded Creds 1             │
  │  Security Issues 2             │
  └─────────────────────────────────┘

  Hallucination density: 1 issue per 47 lines. That's a lot.

  ──────────────────────────────────────────────────────────
  Run vibecheck scan for the full breakdown.

vibecheck context

Intent-aware context, evolution from provenance, and proactive hints for focused files.

vibecheck context --evolve
vibecheck context --intent "authentication"
vibecheck context --intent "where do we handle auth" --semantic
vibecheck context --proactive --file packages/api/src/routes/auth.ts

Flags:

| Flag | Description | |------|-------------| | --evolve | Learn from provenance (edits.jsonl); write co-edits, sequences, outcome scores to learned.json | | --intent <query> | Query codebase by natural language → files, symbols | | --semantic | Use embeddings for intent query (slower, finds conceptually related code) | | --proactive | Proactive context for focused file | | --file <path> | Focused file path (required with --proactive) | | --json | Machine-readable output |

Output Formats

All commands that produce findings support --json for machine-readable output. The JSON schema is stable across patch versions.

Finding schema

interface Finding {
  id: string;
  engine: string;
  severity: 'critical' | 'high' | 'medium' | 'low';
  ruleId: string;
  category: string;
  file: string;
  line: number;
  column: number;
  message: string;
  evidence: string;       // the offending code snippet
  suggestion?: string;    // how to fix it
  confidence: number;     // 0.0–1.0
  autoFixable: boolean;
}

SARIF export

The underlying FileRunner supports SARIF 2.1.0 for GitHub Code Scanning integration. Use --json and pipe to a SARIF converter, or use the GitHub Action which handles this automatically.

Ignore Patterns

Create .vibecheckignore at your project root:

# Ignore generated files
src/generated/**

# Ignore specific file
src/legacy/old-api.ts

# Wildcards
**/*.test.ts

Environment Variables

| Variable | Description | |----------|-------------| | NO_COLOR | Disable color output (same as --no-color) | | VIBECHECK_THRESHOLD | Default confidence threshold | | VIBECHECK_WORKSPACE | Override workspace root detection |

Integration

package.json scripts

{
  "scripts": {
    "vibecheck": "vibecheck scan .",
    "vibecheck:guard": "vibecheck guard . --threshold 70",
    "vibecheck:score": "vibecheck score ."
  }
}

Pre-commit hook

# .husky/pre-commit
vibecheck guard . --fail-on critical

Shell completion

Enable tab completion for commands:

Bash:

eval "$(vibecheck completion bash)"
# Or append to ~/.bashrc:
vibecheck completion bash >> ~/.bashrc

Zsh:

eval "$(vibecheck completion zsh)"
# Or append to ~/.zshrc:
vibecheck completion zsh >> ~/.zshrc

License

MIT — see LICENSE.