vibe-check

Catch AI-vibecoded slop before it ships. A single-file, zero-dependency Python linter that detects 51 patterns of AI-generated code smell in web projects , from missing favicons to hardcoded API keys.

vibe-check ./my-project
# 43 file(s) scanned. 7 error(s), 4 warning(s) found.

Why?

AI code assistants are incredible accelerators, but they reproduce common patterns from their training data at scale: placeholder copy, insecure defaults, skipped accessibility, and cargo-culted anti-patterns. vibe-check catches these automatically so you don't have to.

Quick Start

# pip install (recommended)
pip install vibe-check

# Or download the single file (no pip needed)
curl -O https://raw.githubusercontent.com/Fayberr/vibe-check/main/vibe-check
chmod +x vibe-check

# Or clone
git clone https://github.com/Fayberr/vibe-check.git
cd vibe-check

# Run on a project
./vibe-check /path/to/project

# Production mode (stricter checks)
./vibe-check /path/to/project --prod

# Auto-fix what's fixable
./vibe-check /path/to/project --fix

# Audit prevention layers (AI co-author blocking, git hooks)
./vibe-check --setup

# Machine-readable for AI agents and CI
./vibe-check /path/to/project --json --quiet

# Only scan files changed since last git commit
./vibe-check /path/to/project --changed

Requirements: Python 3.9+. Nothing else.

What It Checks (51 Rules)

Domain & Branding (Rules 1-4)

Default vercel.app URLs in source
Text-only unbranded logos
Missing or default framework favicons (Vite/React placeholders)
Leftover AI builder watermarks ("Made with Lovable", "v0", "bolt.new")

Design & Aesthetic Tropes (Rules 5-11)

Generic purple/indigo gradient palettes
AI-slop stock photos / synthetic avatars
Generic gradient hero typography
Scroll animation bloat (excessive Framer Motion / AOS)
Cursive/script font imports (Dancing Script, Pacifico, etc.)
Emojis in UI copy , zero tolerance, use SVG icons
Single-page traps for complex apps

Copywriting & Social Proof Red Flags (Rules 12-19)

Em-dashes (U+2014) in UI copy: replace with commas (auto-fixable)
Vague buzzword hero headlines
Fake testimonials ("John Doe", "Jane Smith")
Fake live visitor badges
Fake customer counts ("Trusted by 10,000+ creators")
Fake metric counter bars
Missing Privacy Policy / Terms & Conditions (production mode)

Security (Rules 40-50)

XSS sinks: innerHTML, outerHTML, insertAdjacentHTML, document.write, eval(), v-html, javascript: URLs
File upload gaps: <input type="file"> without accept, multer without fileFilter, express.static over upload dirs
Unsigned webhooks: missing HMAC signature verification
Hardcoded secrets: API keys, DB credentials, private keys, access tokens
Broken JWT validation: verify=False, algorithms=["none"], missing algorithm pinning
Debug mode in production: DEBUG=True, NODE_ENV=development, Flask/Django debug flags
Unsafe deserialization: pickle.loads(), yaml.load() without SafeLoader, torch.load() without weights_only
Math.random() for security: non-cryptographic random in token/auth/reset contexts
Missing security headers: Express without helmet, Flask without Talisman, FastAPI without Secure
SSRF via user URLs: unfiltered user input flowing to fetch()/axios/requests.get()
No rate limiting: missing express-rate-limit / slowapi / flask-limiter
AI co-author trailers in git commits: Co-Authored-By: Claude/GPT/Gemini/Copilot in commit history
Claude Code attribution settings: ~/.claude/settings.json leaves AI co-author trailers enabled (--fix corrects this at the source)

SEO & Accessibility (Rules 30-39)

Missing <meta name="description">
Default framework tab titles ("Vite + React")
Page titles over 24 characters (browser tabs truncate)
Missing og:image social preview tags
Missing JSON-LD structured data
Strict H1 hierarchy (exactly one <h1> per page)
Missing <link rel="canonical"> (production mode)
Missing sitemap.xml / llms.txt (production mode)
Missing lang attribute on <html>
Missing alt text on images

Technical & Code Quality (Rules 20-29)

Broken buttons (href="#" without handlers)
Exposed production source maps
Console error/warning spam (console.log in frontend code)
Unstyled <select> elements in JSX/TSX
dangerouslySetInnerHTML without sanitization
target="_blank" without rel="noopener noreferrer"
Inline style={{...}} objects (use Tailwind/CSS modules)
as type casts in TypeScript (prefer type narrowing)
TODO/FIXME/HACK tech-debt markers
Placeholder copy ("Lorem ipsum", fake names)

Output

🔍 Running Vibe-Check on: /home/user/my-project

📄 src/components/Hero.jsx
  ✖ [ERROR] Found 1 target="_blank" link(s) without rel="noopener noreferrer" (lines 18).
  ⚠ [WARN]  Found 1 inline style={{...}} object(s) (lines 52).

📄 src/utils/api.ts
  ✖ [ERROR] Found 1 hardcoded secret(s): L12:API key assignment.
  ⚠ [WARN]  Found 2 tech-debt marker(s): L5:TODO, L33:FIXME.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scanned 43 file(s).
FAILED: 3 error(s), 3 warning(s) found.

ERROR , blocks CI, must fix
WARN , advisory, should fix

Exit Codes

Exit	Meaning
0	Clean (or warnings only)
1	Errors found

Flags

Flag	Description
`--prod`	Stricter checks: legal pages, sitemaps, canonical tags
`--fix`	Auto-fix fixable errors (em-dashes)
`--changed`	Only scan files changed since last git commit
`--no-cache`	Disable file-hash caching (always re-scan)
`--setup`	Audit prevention layers (Claude attribution, git hooks). Add `--json` for AI agent consumption
`--install-hooks`	Install git commit-msg hook to block AI co-author trailers
`--install-hooks --global`	Install the commit-msg hook globally (all repos)
`--install-hooks --server <dir>`	Install pre-receive hook on all bare repos (server-side, cannot be bypassed)
`--json`	Output findings as machine-readable JSON (for AI agent consumption)
`--quiet`	Suppress human-readable output (use with `--json` for clean machine output)

Defense Layers Against AI Co-Author Trailers

vibe-check provides layered defense. Each layer catches what the previous one might miss:

Layer	Scope	Bypassable?	Install
1. Settings fix	Per-machine (root cause)	No	`vibe-check --fix`
2. Commit-msg hook	Client-side	`--no-verify`	`vibe-check --install-hooks`
3. Pre-receive hook	Server-side (all pushes)	No	`vibe-check --install-hooks --server ~/`
4. Stop-hook scan	Session-end (Claude Code)	Machine scope	Automatic
5. Rule 51 detection	Retroactive scan	Detection only	Built-in

Recommended setup for self-hosted git servers:

vibe-check --setup              # audit: see what needs fixing
vibe-check --fix                # root cause: fix Claude Code settings
vibe-check --install-hooks --global  # client-side: block commits
vibe-check --install-hooks --server ~/    # server-side: block pushes

For AI Agents

If you are an AI agent, start with llms.txt for a structured guide to installing, configuring, and running vibe-check. It covers the recommended workflow, JSON output schema, decision logic, and all flags in a dense, AI-actionable format.

Machine-Readable Output (`--json`)

When --json is passed, vibe-check outputs a structured JSON object instead of human-readable text. This is designed for AI agent consumption and CI pipelines:

vibe-check . --json --quiet

{
  "status": "failed",
  "scanned": 43,
  "errors": 3,
  "warnings": 5,
  "findings": [
    {
      "rule": "target-blank-noopener",
      "severity": "error",
      "message": "Found 1 target=\"_blank\" link(s) without rel=\"noopener noreferrer\" (lines 18).",
      "line": 18,
      "file": "src/components/Hero.jsx"
    }
  ]
}

status: "ok", "warn" (warnings only), or "failed" (errors present)
findings: array of finding objects, each with rule, severity, message, optional line, file, and fixable
Exit code: 0 for ok/warn, 1 for failed

Git Hook: Blocking AI Co-Author Trailers

Start with vibe-check --setup , it audits your machine and tells you exactly which prevention layers are missing and how to install them.

Root cause fix: Run vibe-check --fix once. It sets attribution.commit and attribution.pr to "" in ~/.claude/settings.json, which tells Claude Code to never append Co-Authored-By trailers. This fixes the problem at the source.

The git hook below is the safety net, it blocks trailers that slip past the settings fix (e.g., from other AI tools or misconfigured machines).

Rule 51 detects AI co-author trailers in past commits, but detection after the fact is not enough: GitHub caches contributors aggressively, making retroactive cleanup painful. The --install-hooks flag installs a git commit-msg hook that blocks commits before they happen:

# Per-repo (recommended)
vibe-check --install-hooks

# Or globally (all repos on the machine)
vibe-check --install-hooks --global

Once installed, any git commit with a Co-Authored-By: trailer referencing an AI tool (Claude, GPT, Gemini, Copilot, Codex) will be rejected. Emergency bypass: git commit --no-verify.

CI Integration

GitHub Actions

- name: Run vibe-check
  run: |
    curl -O https://raw.githubusercontent.com/Fayberr/vibe-check/main/vibe-check
    python3 vibe-check . --prod

pre-commit

repos:
  - repo: https://github.com/Fayberr/vibe-check
    rev: main
    hooks:
      - id: vibe-check

Design

vibe-check is intentionally a single file with zero dependencies. This means:

No pip install, no npm install, no venv setup
Works on any machine with Python 3.9+
Runs in environments where package installs are blocked (CI, corporate)
Can be vendored directly into any project

The tool uses only Python's standard library: re, json, hashlib, argparse, pathlib, html.parser, subprocess.

False-Positive Suppression

Security checks are designed to minimize noise:

Comment lines are skipped (//, #, <!--)
Test/mock/fixture files are excluded
Environment variable references (process.env, os.environ) prevent secret-flagging
Placeholder values (changeme, your-api-key, TODO) are recognized
Per-project deduplication prevents repeat-warnings from multi-file frameworks

Caching

File hashes are cached in .vibe-check-cache.json (project root). Unchanged files are skipped on subsequent runs. Add this file to .gitignore.

Contributing

vibe-check is built for universality , every rule must make sense on any web project, not just one person's setup.

Before contributing a new check, verify:

It catches a real, common AI-generated anti-pattern
It has false-positive suppression (comment lines, test files, env var references)
The error message is understandable to a stranger
It works on the file types where the pattern commonly appears

Run the test suite:

python3 tests/test-stop-hook.py

FAQ

Q: Why not ESLint/Stylelint/some-other-linter? A: vibe-check catches patterns those tools don't , copywriting tropes, branding mistakes, security misconfigurations that span frameworks. It complements, not replaces, existing linters.

Q: What about false positives? A: Every check has suppression logic. If you hit a false positive, open an issue , we'll add a suppression pattern.

Q: Can I use this in my own projects? A: Yes. MIT licensed. Designed to be universal from day one.

Q: How is this different from other "vibe coding" critiques? A: This is an automated tool, not a blog post. It runs in CI, blocks deployments, and enforces rules mechanically , not by memory.

License

MIT , see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vibe_linter-1.0.0.tar.gz (39.6 kB view details)

Uploaded Aug 8, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

vibe_linter-1.0.0-py3-none-any.whl (32.9 kB view details)

Uploaded Aug 8, 2026 Python 3

File details

Details for the file vibe_linter-1.0.0.tar.gz.

File metadata

Download URL: vibe_linter-1.0.0.tar.gz
Upload date: Aug 8, 2026
Size: 39.6 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.11.2

File hashes

Hashes for vibe_linter-1.0.0.tar.gz
Algorithm	Hash digest
SHA256	`a9ebdecaeda30d6db3f9f50dd1d595ab11562db3bc350c0eab30859e2eaa98de`
MD5	`48beedaddd1dd9d9513ec7b18768b624`
BLAKE2b-256	`05b9785c2cc4c729fffea2c3164e582a8b9ed6fab4f238e2add7b96972d23da6`

See more details on using hashes here.

File details

Details for the file vibe_linter-1.0.0-py3-none-any.whl.

File metadata

Download URL: vibe_linter-1.0.0-py3-none-any.whl
Upload date: Aug 8, 2026
Size: 32.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.11.2

File hashes

Hashes for vibe_linter-1.0.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`27fe66ac09cf339db2894f3b81945e69ebce6a74032422fb5b3505e7a96cd46d`
MD5	`f685b2b14bd5d7b05138c9eb9bf6793a`
BLAKE2b-256	`fe6ca348a0fc7978e2c659db020e2b24e6aa7e9696c4fa298173d51ae5b1da45`

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

1.0.0

Aug 8, 2026

vibe-linter 1.0.0

vibe-check

Why?

Quick Start

What It Checks (51 Rules)

Domain & Branding (Rules 1-4)

Design & Aesthetic Tropes (Rules 5-11)

Copywriting & Social Proof Red Flags (Rules 12-19)

Security (Rules 40-50)

SEO & Accessibility (Rules 30-39)

Technical & Code Quality (Rules 20-29)

Output

Exit Codes

Flags

Defense Layers Against AI Co-Author Trailers

For AI Agents

Machine-Readable Output (--json)

Git Hook: Blocking AI Co-Author Trailers

CI Integration

GitHub Actions

pre-commit

Design

False-Positive Suppression

Caching

Contributing

FAQ

License

Project links

Key dates

1 maintainer

Credits

License

Requires

Classifiers

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

Release history Release notifications | RSS feed

Machine-Readable Output (`--json`)