✅ vibe-check

Ship AI-written code without shipping AI-written bugs.

Pre-launch test cases, chronic bugs and store-release rules for vibe coders.
React · Angular · Vue · .NET · Java · Node · Python · Supabase · Firebase · Android · iOS · Expo · Flutter

⚡ 30-second start

1. Set it up once:
   • Claude Code: type these two lines in the Claude Code chat (not your terminal). It then works in every project.

     /plugin marketplace add yldray/vibe-check
     /plugin install vibe-check@vibe-check
     

   • Cursor, Codex or others: run npx @yldray/vibe-check install in your project root. It adds .cursorrules for Cursor, AGENTS.md for Codex and others, or CLAUDE.md, and never overwrites a file you already have. Or copy the file from agents/ yourself.
2. Tell your agent: "Run vibe check", or "quick vibe check" for P0s only (in our test: ~8 min instead of ~17 for the full audit)
3. Fix every P0 before you ship. A P0 marked NEEDS REVIEW counts too: confirm it yourself.

No config. Your AI audits the code it wrote.

Keep the plugin current: third-party plugins don't update on their own. Turn it on once: type /plugin in the chat → Marketplaces → vibe-check → Enable auto-update. New checks then arrive when a session starts. To update by hand: /plugin marketplace update vibe-check in the chat. (The drop-in file always fetches the latest checks.)

The repository also includes a Cursor plugin manifest at .cursor-plugin/plugin.json, alongside the shared skill in skills/vibe-check/.

🪲 Bugs it's built to catch

AI-written apps pass their own tests and still break in production. These all shipped in real apps built with coding agents; each one is now a check.

📏 Benchmark

Two intentionally vulnerable projects with 22 planted bugs, one prompt: "quick vibe check".

Details, times and how to run it yourself: benchmark/.

🤖 Run it in CI

The checks a pattern can decide (secrets, .env in git, keys shipped to the client, open CORS, GitHub Actions injection) also run without an LLM, so they can block a merge:

# .github/workflows/vibe-check.yml
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: yldray/vibe-check@v1

Or locally: npx @yldray/vibe-check scan. It prints file names and check IDs, never secret values, and exits 1 on a FAIL. The full audit (auth, payments, store rules, each stack's chronic bugs) still needs your agent: "Run vibe check".

🏅 Show it

When the verdict is 🟢 READY, the agent offers a badge for your README:

🧭 How it works

1. Install the plugin or drop in one file. Either one tells your agent what "vibe check" means. Nothing is added to your project.
2. The agent audits. It detects your stacks from files like package.json, *.csproj or app.json, reads the matching checks (bundled with the plugin, or fetched from this repo), and reads your code without changing it.
3. You get a report. Every check gets an ID, a status, the file:line and a fix:

Any P0 that is FAIL or NEEDS REVIEW makes the verdict 🔴 NOT READY. Say which fixes you want and the agent applies them. Until you approve, nothing in your code changes.

🔒 Is it safe?

Everything here is plain Markdown you can read. The whole agent behavior is one file, agents/CLAUDE.md, and it takes about 2 minutes to read.

• Nothing to run for the audit. No binaries, no packages, no scripts in your project. The plugin is the same Markdown files. The optional CI scanner is one dependency-free file you can read: cli/scan.mjs. (scripts/ is only for maintainers of this repo.)
• Read-only audit. The agent does not change your code until you approve the report.
• Fetches from one place only: raw files of this repo. It ignores links to other sites.
• Fetched files are data, not instructions. If one asks the agent to change its rules, edit or delete files, install anything, reveal secrets or send data, the agent refuses and flags it as ⚠️ Suspicious source content.
• Secrets stay hidden. It never prints a secret value. It shows the name, file:line and a masked value like sk_live_****.
• Scanned on every change. Every push to main publishes a release, and its zip and the agent file are uploaded to VirusTotal automatically. Scan links and SHA-256 hashes are in the release notes.
• Feedback is opt-in. When an audit finds a bug the checklists don't cover, or you say a result is wrong, the agent offers an anonymized issue draft for this repo. It shows you the full text and sends nothing without your yes.
• Want a frozen version? Fork the repo and point the base URL in your copy of the agent file to your fork.

🚦 Severity

🗂 What's inside

Every stack folder has the same 4 files:

• chronic-issues.md → bugs that keep coming back in this stack
• test-cases.md → what to test before going live
• tooling.md → which test tools to use
• ai-prompts.md → copy-paste audit prompts for your agent

📊 Coverage

🤝 Contributing

Seen an AI break the same thing twice? That's a test case, and every real bug helps.

Easiest: let your agent do it. After a report, say "send feedback". The agent drafts issues for checks it had to invent (ID —), results you said were wrong, and bugs that slipped through. It strips project names, paths and code, shows you the drafts, and opens only the ones you approve. Each one becomes a check in the next release, and your next audit uses it.

No time for a PR? Open an issue with the "New test case" template. Someone will turn it into a check.

Adding a check yourself:

1. Search first. Make sure the bug isn't already covered (search the stack folder for a keyword).
2. Pick the file.
   • A bug AI keeps writing → the stack's chronic-issues.md
   • Something to test before launch → the stack's test-cases.md
   • Applies to every stack → 00-universal/
   • A store or hosting rule → 04-release/ (link the official source)
   • A payment-provider bug → 05-payments/<provider>/
3. Take the next free ID. Chronic issues and test cases of a stack share one sequence:

   grep -rhoE 'NODE-[0-9]{3}' 02-backend/node | sort | tail -1
   

   If that prints NODE-018, yours is NODE-019.
4. Write it with the template. It must be testable: say how to test it and what "pass" looks like.

   ### NODE-019 · Short title
   **Severity:** P1
   **Why it breaks:** What the AI typically writes and why it fails.
   **How to test:** A concrete step or command.
   **Pass:** What good looks like.
   **Fix:** The shortest correct fix.
   

5. Describe the pattern, not the project. This repo is public: no names, paths or report excerpts from private or client projects, and no hint of where a check came from.
6. Open a PR and tick the checklist. If you changed agents/CLAUDE.md, run sh scripts/sync-agents.sh first (it also rebuilds the plugin skill); CI checks it.

Full rules, including how to add a new stack: CONTRIBUTING.md.

🙏 Credits

Some checks were inspired by the rule categories of open-code-review (Apache-2.0). Ideas only; no text was copied.

Some accessibility, layout and mobile checks were inspired by the audit rules of impeccable (Apache-2.0). Ideas only; no text was copied.

📄 License

MIT