vibecheck

39 rules for catching AI-generated code smells. ESLint for AI slop.

npx @yuvrajangadsingh/vibecheck .

  src/api/routes.ts
    12:5    error  no-hardcoded-secrets   Hardcoded secret detected. Use environment variables instead.
    45:3    error  no-empty-catch         Empty catch block swallows errors silently.
    89:1    warn   no-console-pollution   console.log left in production code.

  src/utils/db.ts
    34:5    warn   no-sql-concat          SQL query built with string concatenation.

  4 problems (2 errors, 2 warnings)
  2 files with issues out of 47 scanned (0.8s)

Why

AI coding tools generate code that works but cuts corners. Empty catch blocks, hardcoded secrets, as any everywhere, comments that restate the obvious. CodeRabbit found AI-generated PRs have 1.7x more issues than human PRs. Veracode reports 45% of AI code samples contain security vulnerabilities.

vibecheck catches these patterns with zero config, zero API keys, zero cost. Runs locally, stays fast.

Install

# Run directly (no install)
npx @yuvrajangadsingh/vibecheck .

# Install globally
npm install -g @yuvrajangadsingh/vibecheck

# Standalone binary (no Node required)
curl -fsSL https://github.com/yuvrajangadsingh/vibecheck/releases/latest/download/vibecheck-darwin-arm64 -o vibecheck
chmod +x vibecheck
./vibecheck .

Standalone binaries (built with Bun) available for macOS (arm64, x64) and Linux (x64, arm64) on the releases page. No Node.js or npm required. Python developers can use these to scan their codebases without installing Node.

What it catches

Security

| Rule | Severity | What it detects | |------|----------|----------------| | no-hardcoded-secrets | error | API keys, tokens, passwords in source code | | no-eval | error | eval() and new Function() calls | | no-sql-concat | warn | SQL queries built with string concatenation | | no-innerhtml | warn | innerHTML and dangerouslySetInnerHTML usage | | no-py-eval | error | eval(), exec(), os.system(), subprocess(shell=True) | | no-py-sql-concat | warn | SQL queries built with f-strings or .format() |

Error Handling

| Rule | Severity | What it detects | |------|----------|----------------| | no-empty-catch | error | Empty catch blocks that silently swallow errors | | no-console-error-only | warn | Catch blocks that only console.error without rethrowing | | no-swallowed-promise | warn | .then() chains without .catch() | | no-vague-error | warn | throw new Error("Something went wrong") and vague Promise.reject | | no-bare-except | error | except: without specifying exception type | | no-pass-except | error | except: pass silently swallowing errors |

Code Quality

| Rule | Severity | What it detects | |------|----------|----------------| | no-console-pollution | warn | console.log/debug/info left in production code | | no-ai-todo | info | AI-generated placeholder TODOs (TODO: implement, FIXME: add) | | no-god-function | warn | Functions over 80 lines | | no-deep-nesting | warn | Code nested 4+ levels deep instead of early returns | | no-double-assertion | warn | Chained assertions like as unknown as T bypassing TypeScript safety | | no-ai-attribution | warn | // Generated by ChatGPT style comments (auto-fixable with --fix) | | no-star-import | warn | from module import * namespace pollution | | no-mutable-default | warn | Mutable default arguments (def foo(bar=[])) | | no-py-print | warn | print() left in production code |

AI-Specific Tells

| Rule | Severity | What it detects | |------|----------|----------------| | no-obvious-comments | info | Comments that restate code (// initialize the counter) | | no-ts-any | warn | TypeScript any types and as any casts | | no-hedging-comments | info | Uncertain comments (// should work, // might not be the best approach) | | no-step-comments | info | Numbered step comments (// Step 1: Initialize) | | no-section-dividers | info | ASCII section dividers (// ========) | | no-narrator-comments | info | // This function handles... narration comments | | no-stub-function | warn | Scaffolding shipped to production (throw "not implemented") | | no-hallucinated-import-js | warn | Imports of packages that don't exist on npm (AI hallucinations) | | no-hallucinated-import-py | warn | Imports of packages that don't exist on PyPI (AI hallucinations) | | no-py-obvious-comments | info | Comments restating code (# initialize the counter) | | no-py-stub-function | warn | Stub functions raising NotImplementedError with no body | | no-py-hedging-comments | info | Hedging comments (# should work, # might not be ideal) | | no-type-ignore-blanket | warn | Blanket # type: ignore without specific error code | | no-unused-protocol | info | Protocol class defined but never referenced (AI ghost scaffold) |

Framework

| Rule | Severity | What it detects | |------|----------|----------------| | no-express-unhandled | warn | Async Express routes without error handling | | no-error-info-leak | error | Error internals (err.message, err.stack) leaked to HTTP responses | | no-flask-debug | warn | Flask app.run(debug=True) in production | | no-with-router | warn | withRouter HOC, deprecated since react-router v6 |

Options

vibecheck [path] [options]
vibecheck rules [--json]

Options:
  -c, --config <file>     Path to config file
  -d, --diff              Only scan lines changed in git diff (unstaged)
  --staged                Only scan lines changed in git diff --cached (staged)
  --diff-stdin            Only scan lines changed in a unified diff read from stdin
  --fix                   Auto-remove fixable findings (AI attribution comments)
  --format <format>       Output format: pretty, compact, json, quiet, gh (default: pretty)
  --json                  Output as JSON (alias for --format json)
  --ignore <patterns...>  Additional ignore patterns
  --severity <level>      Minimum severity to report: error, warn, info (default: warn)
  --fail-on <level>       Exit 1 at this severity: error, warn, info, never (default: error)
  --max-warnings <n>      Exit 1 when more than n warnings are reported
  --statistics            Append per-rule finding counts (pretty and json output)
  -q, --quiet             Only show summary (alias for --format quiet)
  --mcp                   Start MCP server (stdio transport)
  -v, --version           Show version
  -h, --help              Show help

--format compact prints one path:line:col severity rule message line per finding (cmd-clickable in most editors). --format gh emits GitHub Actions workflow commands so findings show up as PR annotations.

vibecheck rules lists every rule with its severity, category, languages, and whether --fix can fix it. vibecheck rules --json emits the same list as JSON.

Exit codes

| Code | Meaning | |------|---------| | 0 | Clean, or no findings at or above --fail-on | | 1 | Findings at or above --fail-on, or --max-warnings exceeded | | 2 | Usage or runtime error (invalid flag, bad path) |

--fail-on and --max-warnings count reported findings only: anything hidden by --severity never fails the run. --fail-on never always exits 0 on a successful scan.

Auto-fix

--fix removes findings that are safe to fix mechanically. Currently that's no-ai-attribution: full-line comments like // Generated by ChatGPT or // Co-Authored-By: Claude get deleted, code lines are never touched. A line is only removed when its content still matches what the scan saw, and results are re-scanned after fixing so reported line numbers stay accurate.

# Strip AI attribution comments across the repo
vibecheck --fix .

Diff mode

Scan only the lines you changed, not the entire codebase. Useful for pre-commit hooks and incremental CI.

# Scan unstaged changes
vibecheck --diff .

# Scan staged changes (pre-commit hook)
vibecheck --staged .

# Scan a diff from anywhere (PRs, other branches)
gh pr diff 42 | vibecheck --diff-stdin .

# CI-friendly output
vibecheck --staged --json .

Paths inside a piped diff are treated as repo-root-relative (what git diff and gh pr diff emit) and resolved against the scan path, so scanning a subdirectory works. Outside a git repository they are taken relative to the scan path.

Pre-commit hook

Add to .git/hooks/pre-commit or use with husky:

#!/bin/sh
npx @yuvrajangadsingh/vibecheck --staged .

Config

Create .vibecheckrc in your project root:

{
  "rules": {
    "no-console-pollution": "off",
    "no-obvious-comments": "warn",
    "no-ts-any": "error"
  },
  "ignore": [
    "node_modules",
    "dist",
    "*.test.ts"
  ]
}

All rules are on by default at their recommended severity. Set any rule to "off" to disable it.

VS Code Extension

Get inline diagnostics (squigglies) right in your editor:

ext install yuvrajangadsingh.vibecheck-linter

Available on the VS Code Marketplace. Works in VS Code, Cursor, and Windsurf.

Features: inline error/warning/info markers, Problems panel integration, status bar count, runs on save.

GitHub Action

Add vibecheck to your CI with inline PR annotations:

- uses: yuvrajangadsingh/[email protected]
  with:
    severity: warn       # minimum severity to report (default: warn)
    fail-on: error       # fail the check at this severity (default: error)
    ignore: "tests/**"   # comma-separated ignore patterns

The action automatically scans only files changed in the PR. On push events, it scans the full repo.

Available on the GitHub Marketplace. See it in action on the demo repo.

CI without the Action

--format gh emits GitHub Actions workflow commands, so findings show up as inline PR annotations from a plain run step:

- run: npx @yuvrajangadsingh/vibecheck . --format gh --fail-on warn

Or keep machine-readable output for other pipelines:

npx @yuvrajangadsingh/vibecheck . --json > vibecheck.json

Pre-commit Hook

Add vibecheck to your pre-commit config:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/yuvrajangadsingh/vibecheck
    rev: v1.2.0
    hooks:
      - id: vibecheck

MCP Server

vibecheck ships with a built-in MCP server so AI coding agents can scan code for slop automatically.

# Start the MCP server
vibecheck --mcp

# Or use the dedicated binary
vibecheck-mcp

Add to your Claude Code, Cursor, or Windsurf config:

{
  "mcpServers": {
    "vibecheck": {
      "command": "npx",
      "args": ["-y", "@yuvrajangadsingh/vibecheck", "--mcp"]
    }
  }
}

3 tools available: scan-files (scan files/directories), scan-diff (scan a git diff), get-rules (list all rules).

How is this different from ESLint?

ESLint catches syntax and style issues. vibecheck catches patterns that are specifically common in AI-generated code.

| | vibecheck | ESLint | sloppylint | |---|---|---|---| | AI-specific rules | 34 | 0 | 100+ | | Hedging comments | yes | no | yes | | Hallucinated imports | yes | no | yes | | Stub detection | yes | no | yes | | Section dividers | yes | no | no | | Step comments | yes | no | no | | Deep nesting | yes | plugin | no | | GitHub Action | yes | community | no | | MCP server | yes | no | no | | VS Code extension | yes | yes | no | | Zero config | yes | no | no | | Languages | JS/TS/Python | JS/TS | Python |

Real-world results

Scanned 31 repos built with Cursor, Bolt, Lovable, Replit, and v0:

• 14,695 issues across 3,597 files
• 46% of all issues were deep nesting
• Cursor repos averaged 6.36 issues/file (highest)
• Each tool leaves a different fingerprint

Full writeup with per-tool breakdowns

How it works

vibecheck uses regex pattern matching to scan your JS/TS/Python files. No AST parsing, no external APIs, no AI. Each rule has a detection pattern and an anti-pattern to reduce false positives.

It skips node_modules, dist, build, __pycache__, .venv, lockfiles, and minified code by default.

If vibecheck saved you a review cycle, consider starring the repo.

Built by Yuvraj Angad Singh. Also: brandmd (extract any site's design system for AI coding agents) and vemb (embeddings from the command line). Follow on GitHub for new dev-tool experiments.

License

FSL-1.1-Apache-2.0