🧠 Vibe Check MCP
Your AI's inner rubber duck when it can't rubber duck itself.
What is Vibe Check?
Vibe Check is a metacognitive pattern interrupt system for the vibe coding era. It provides the essential "Hold on... this ain't it" moment that your AI assistants can't generate for themselves.
It's not about making your AI smarter—it's about adding the layer of doubt, questioning, and course correction that humans naturally apply to their own thought processes.
The Problem: Pattern Inertia
In the vibe coding movement, we're all using LLMs to generate, refactor, and debug our code. But these models have a critical flaw: once they start down a reasoning path, they'll keep going even when the path is clearly wrong.
You: "Parse this CSV file"
AI: "First, let's implement a custom lexer/parser combination that can handle arbitrary
CSV dialects with an extensible architecture for future file formats..."
You: *stares at 200 lines of code when you just needed to read 10 rows*
This pattern inertia leads to:
- 🔄 Tunnel vision : Your agent gets stuck in one approach, unable to see alternatives
- 📈 Scope creep : Simple tasks gradually evolve into enterprise-scale solutions
- 🔌 Overengineering : Adding layers of abstraction to problems that don't need them
- ❓ Misalignment : Solving an adjacent but different problem than the one you asked for
Features: Metacognitive Oversight Tools
Vibe Check adds a metacognitive layer to your agent workflows with three integrated tools:
🛑 vibe_check
Pattern interrupt mechanism that breaks tunnel vision with metacognitive questioning:
vibe_check({
"phase": "planning", // planning, implementation, or review
"userRequest": "...", // FULL original user request
"plan": "...", // Current plan or thinking
"confidence": 0.7 // Optional: 0-1 confidence level
})
⚓ vibe_distill
Meta-thinking anchor point that recalibrates complex workflows:
vibe_distill({
"plan": "...", // Detailed plan to simplify
"userRequest": "..." // FULL original user request
})
🔄 vibe_learn
Self-improving feedback loop that builds pattern recognition over time:
vibe_learn({
"mistake": "...", // One-sentence description of mistake
"category": "...", // From standard categories
"solution": "..." // How it was corrected
})
Real-World Impact
Vibe Check in Action
Figure 1: Vibe Check identifies ambiguity in terminology (MCP) and prompts for clarification
Figure 2: After Vibe Check feedback, proper search techniques are used to clarify ambiguous terms
Before & After
Before Vibe Check:
User: "Write a function to check if a string is a palindrome"
Agent: *generates 150 lines of code with custom character handling classes,
internationalization support, and a factory pattern*
After Vibe Check:
User: "Write a function to check if a string is a palindrome"
Agent: *starts complex approach*
Vibe Check: "Are we sure we need a class-based approach for this simple string operation?"
Agent: *course corrects*
return s === s.split('').reverse().join('');
Installation & Setup
Installing via Smithery
To install vibe-check-mcp-server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @PV-Bhat/vibe-check-mcp-server --client claude
Manual Installation
# Clone the repo
git clone https://github.com/PV-Bhat/vibe-check-mcp-server.git
cd vibe-check-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
# Start the server
npm run start
Integration with Claude
Add to your claude_desktop_config.json:
"vibe-check": {
"command": "node",
"args": [
"/path/to/vibe-check-mcp/build/index.js"
],
"env": {
"GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
}
}
Environment Configuration
Create a .env file in the project root:
GEMINI_API_KEY=your_gemini_api_key_here
Agent Prompting Guide
For effective pattern interrupts, include these instructions in your system prompt:
As an autonomous agent, you will:
1. Treat vibe_check as a critical pattern interrupt mechanism
2. ALWAYS include the complete user request with each call
3. Specify the current phase (planning/implementation/review)
4. Use vibe_distill as a recalibration anchor when complexity increases
5. Build the feedback loop with vibe_learn to record resolved issues
When to Use Each Tool
| Tool |
When to Use |
| 🛑 vibe_check |
When your agent starts explaining blockchain fundamentals for a todo app |
| ⚓ vibe_distill |
When your agent's plan has more nested bullet points than your entire tech spec |
| 🔄 vibe_learn |
After you've manually steered your agent back from the complexity abyss |
API Reference
See the Technical Reference for complete API documentation.
Architecture
The Metacognitive Architecture (Click to Expand)
Vibe Check implements a dual-layer metacognitive architecture based on recursive oversight principles. Key insights:
Pattern Inertia Resistance : LLM agents naturally demonstrate a momentum-like property in their reasoning paths, requiring external intervention to redirect.
Phase-Resonant Interrupts : Metacognitive questioning must align with the agent's current phase (planning/implementation/review) to achieve maximum corrective impact.
Authority Structure Integration : Agents must be explicitly prompted to treat external metacognitive feedback as high-priority interrupts rather than optional suggestions.
Anchor Compression Mechanisms : Complex reasoning flows must be distilled into minimal anchor chains to serve as effective recalibration points.
Recursive Feedback Loops : All observed missteps must be stored and leveraged to build longitudinal failure models that improve interrupt efficacy.
For more details on the underlying design principles, see Philosophy.
Documentation
Contributing
We welcome contributions to Vibe Check! Whether it's bug fixes, feature additions, or just improving documentation, check out our Contributing Guidelines to get started.
License
MIT
