---

Why I Built This

We're in the vibe coding era. People who can't read code are building real software - shipping apps, automating workflows, creating tools that actually work. The barrier to entry has dropped.

But there's a problem. You built something. It runs. Is this production-ready? You have no idea. You can't read the code. You're taking the AI's word for it.

I've spent over a decade as a full-stack developer and enterprise architect. Now as a founder, I mostly orchestrate AI agents - and I keep running into non-technical founders who vibe-coded their way to a working prototype and hit a wall. They don't know what's broken. They don't know what's "good enough" to ship. They just know they can't read the code.

So I built this. One command gives you:

- A prioritized action plan — What to fix first, what can wait, what's fine
- Plain-language findings — What's actually wrong, with file paths you can point at
- Agent vs. human classification — What your AI tool can auto-fix, what needs a human
- Handoff artifacts — Documents you can give to a technical co-founder, a freelancer, or your next AI session

It's founder-focused. It knows the difference between "enterprise best practice" and "good enough to get in front of users."


---

What You Get

`
.vibe-check/
├── summary.md # 1-page executive overview
├── report.md # Full report with scores
├── action-plan.md # Prioritized fix list
├── metadata.json # Machine-readable data
├── analysis/ # Raw codebase analysis
└── checklist/
├── index.md # All items overview
└── item-001-*.md # Individual findings with fix instructions
`

Each checklist item includes:
- Current State — What was found, with file paths and line numbers
- Impact — What happens if you don't fix it (plain language)
- How to Fix — Step-by-step instructions
- Agent-Doable — Whether Claude can fix it for you

---

How It Works

$3

`
/vibe-check:check
`

The system:
1. Asks context — What you're building, who it's for, what data you handle, what's at stake
2. Maps your codebase — Spawns an agent to analyze secrets, auth, errors, dependencies, infrastructure, and detect capabilities (database, auth, analytics, etc.)
3. Assesses domains — Parallel agents evaluate security, discoverability, analytics, platform, reliability, legal (calibrated to your context). Domains that don't apply are automatically skipped.
4. Writes results — Score, report, prioritized action plan

You get a score out of 100 and a clear breakdown of what needs attention. Small codebases (<50 files) get a fast-path mapper that cuts assessment time significantly.

$3

`
/vibe-check:discuss
`

Ask questions about your report:
- "Tell me more about the secrets management issue"
- "What should I fix first?"
- "Why is authentication marked as failing?"

$3

Auto-fix agent-doable items with verified, atomic commits:

`
/vibe-check:fix # Fix all agent-doable items
/vibe-check:fix item-003 # Fix a specific item
`

Each fix is verified (lint, typecheck, tests as applicable) and committed individually.

For items that need manual work, ask for help:

`
/vibe-check:discuss
> "Help me with the privacy policy item"
`

$3

`
/vibe-check:refresh
`

Re-runs the assessment and shows what improved or regressed since last check.

---

Commands

| Command | Description |
|---------|-------------|
| /vibe-check:check | Full production readiness assessment |
| /vibe-check:fix | Auto-fix agent-doable items with atomic commits |
| /vibe-check:refresh | Re-run and compare with previous results |
| /vibe-check:discuss | Ask questions about your report |
| /vibe-check:help | Show command reference |
| /vibe-check:map-codebase | Standalone codebase analysis |

---

Score Bands

| Score | Band | Meaning |
|-------|------|---------|
| 70-100 | Ready | Production-ready with minor improvements |
| 40-69 | Needs Work | Significant gaps to address |
| 0-39 | Not Ready | Critical issues that must be fixed |

Domains and items that don't apply to your project (no database, no analytics, etc.) are automatically marked N/A and excluded from scoring — so your score reflects reality for your project type. If any Critical-priority item is failing, the band is capped at "Needs Work" regardless of score.

---

What Gets Assessed

$3

- Secrets management (hardcoded keys, .env handling)
- Authentication patterns
- Input validation
- Dependency vulnerabilities
- HTTPS configuration

$3

- Meta tags (title, description)
- OpenGraph tags for social sharing
- Twitter cards
- Sitemap and robots.txt
- Semantic HTML structure

$3

- Visitor tracking setup
- Error tracking (Sentry, etc.)
- Conversion event tracking

$3

- Hosting compatibility
- Complexity check (over-engineering signals)
- Cost trap patterns
- Managed service opportunities

$3

- Backup configuration
- Error handling patterns
- Database connection management
- Health check endpoints

$3

- Privacy policy
- Terms of service
- Cookie consent
- User data deletion capability

---

Installation

`bash
npx vibe-check-cc
`

The installer prompts you to choose:
- Global (~/.claude) — Available in all projects
- Local (./.claude) — Current project only

$3

`bash

Global install

npx vibe-check-cc --global

Local install

npx vibe-check-cc --local

Uninstall

npx vibe-check-cc --global --uninstall
`

$3

`
/vibe-check:help
`

$3

Vibe Check spawns multiple agents and runs various tools. For a frictionless experience, run Claude Code with:

`bash
claude --dangerously-skip-permissions
`

---

Updating

`bash
npx vibe-check-cc@latest
`

---

How It's Built

$3

Vibe Check uses specialized agents to keep context focused:

| Agent | Job |
|-------|-----|
| Orchestrator | Coordinates the assessment, writes final reports |
| Mapper | Explores codebase, writes analysis files |
| Assessors | Evaluate specific domains, write checklist items |
| Fixer | Applies fixes with verification and atomic commits |

The orchestrator stays lean (under 30% context). Heavy exploration and evaluation happen in subagents with fresh context windows.

$3

The assessment output lives in .vibe-check/ which you might commit. Here's how we handle secrets:

What we do:
- Agents are instructed to never read .env files, only check if they exist
- Agents are instructed to report secret types and locations, never actual values
- A pre-write hook scans all output for 50+ secret patterns (from gitleaks) and blocks writes if detected

What we can't guarantee:
- The agents are non-deterministic — instructions aren't guarantees
- The regex scanner catches common patterns but not everything
- Novel secret formats or obfuscated values could slip through

What you should do:
- Review .vibe-check/ before committing
- Keep .vibe-check/ in .gitignore if you're not sure
- Run git diff before pushing

---

Troubleshooting

Commands not found?
- Restart Claude Code to reload commands
- Verify files exist in ~/.claude/commands/vibe-check/

Want to re-run?
- Delete .vibe-check/ and run /vibe-check:check again
- Or use /vibe-check:refresh` to update existing assessment

---

Vibe Check on Vibe Check

We run vibe-check on itself. Here's the result:



The perfect score comes from being appropriately minimal: zero dependencies (no supply chain risk), no secrets required, no user data collected, and operates entirely on the local filesystem.



---

Acknowledgements

The multi-agent architecturem, orchestration patterns and even this README in Vibe Check are heavily inspired by GSD (Get Shit Done) — a structured planning and execution framework for Claude Code. If you're building AI-assisted workflows with parallel agents and good context engineering principles, check out their approach.

---

License

MIT

---

Star History