Production readiness assessment for Claude Code - identify gaps across security, infrastructure, and reliability
npm install vibe-check-cctxt
__ __ ______ _______ ________ ______ __ __ ________ ______ __ __
| \ | \| \| \ | \ / \ | \ | \| \ / \ | \ / \
| $$ | $$ \$$$$$$| $$$$$$$\| $$$$$$$$ | $$$$$$\| $$ | $$| $$$$$$$$| $$$$$$\| $$ / $$
| $$ | $$ | $$ | $$__/ $$| $$__ | $$ \$$| $$__| $$| $$__ | $$ \$$| $$/ $$
\$$\ / $$ | $$ | $$ $$| $$ \ | $$ | $$ $$| $$ \ | $$ | $$ $$
\$$\ $$ | $$ | $$$$$$$\| $$$$$ | $$ __ | $$$$$$$$| $$$$$ | $$ __ | $$$$$\
\$$ $$ _| $$_ | $$__/ $$| $$_____ | $$__/ \| $$ | $$| $$_____ | $$__/ \| $$ \$$\
\$$$ | $$ \| $$ $$| $$ \ \$$ $$| $$ | $$| $$ \ \$$ $$| $$ \$$\
\$ \$$$$$$ \$$$$$$$ \$$$$$$$$ \$$$$$$ \$$ \$$ \$$$$$$$$ \$$$$$$ \$$ \$$
`
You built something with AI. You can't read the code. Is it actually ready to ship?
Get a structured assessment you can understand, discuss, and hand off.




`bash
npx vibe-check-cc
`
Works on Mac, Windows, and Linux.
.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