🧠 Vibe Check MCP

What is Vibe Check?

Vibe Check is a metacognitive layer that keeps AI coding agents honest. It pauses the agent at key moments, challenges shaky assumptions and records what worked (or failed) so the next run is smarter. Think of it as the agent's inner rubber duck—always nudging the conversation back to the user's actual needs.

TL;DR: Vibe Check makes AI coding agents more resilient and aligned by enforcing moments of reflection.

The Problem: Pattern Inertia

LLMs often follow the first solution they imagine. Once that pattern takes hold they elaborate on it even if it drifts from the original goal. Without an external nudge the agent seldom questions its direction, leading to misalignment, overengineering and wasted cycles.

Key Features

• vibe_check – pattern interrupt tool using the learnlm-2.0-flash-experimental model (with automatic fallback to gemini-2.5-flash and gemini-2.0-flash) for up to a 1M token context window.
• vibe_learn – records mistakes, preferences and successes to build a rich learning history that feeds back into vibe_check.
• Large context awareness – the full learning log is summarized and included in prompts so the model can spot recurring patterns and reinforce successful approaches.

These two tools feed each other. vibe_check interrupts questionable plans, vibe_learn captures the lesson, and the growing log informs the next vibe_check call via the model's 1M token context window.

[vibe_check] <----> [vibe_learn]
      ^                |
      |________________|

The more your agent works, the more context Vibe Check has to keep it on the right path.

Installation

# Clone and install
git clone https://github.com/PV-Bhat/vibe-check-mcp-server.git
cd vibe-check-mcp-server
npm install
npm run build

Create a .env file with your API key:

GEMINI_API_KEY=your_gemini_api_key

Start the server:

npm start

Docker

To run the server in a container:

docker build -t vibe-check-mcp .
docker run -e GEMINI_API_KEY=your_gemini_api_key -p 3000:3000 vibe-check-mcp

Integrating with Claude Desktop

Add to 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" }
}

Agent Prompting Essentials

In your agent's system prompt make it clear that vibe_check is a mandatory pattern interrupt. Always pass the full user request and specify the current phase (planning, implementation, or review). After correcting a mistake, log it with vibe_learn so the system can recognize it next time.

Example snippet:

As an autonomous agent you will:
1. Call vibe_check after planning and before major actions.
2. Provide the full user request and your current plan.
3. Record resolved issues with vibe_learn so future checks get smarter.

When to Use Each Tool

| Tool | Purpose | |------|---------| | 🛑 vibe_check | Challenge assumptions and prevent tunnel vision | | 🔄 vibe_learn | Capture mistakes, preferences and successes |

Documentation

• Agent Prompting Strategies
• Advanced Integration
• Technical Reference
• Philosophy
• Case Studies

Contributing

Contributions are welcome! See CONTRIBUTING.md.

License

MIT