Vibe Check
STDIOAI agent mentor layer preventing over-engineering through research-backed Chain-Pattern Interrupts and metacognitive oversight
AI agent mentor layer preventing over-engineering through research-backed Chain-Pattern Interrupts and metacognitive oversight
KISS overzealous agents goodbye — stop over-engineering; ship the minimal viable path first.
Based on research
In our study agents calling Vibe Check improved success (27 → 54%) and halved harmful actions (83 → 42%).
-0b7285?style=flat-square){kind=icon}
32.3k installs on PulseMCP • 12.8k this week • featured on “Most Popular (This Week)” • 2k+ monthly calls on Smithery.ai • research-backed oversight • STDIO + streamable HTTP transport
Plug-and-play mentor layer that stops agents from over-engineering and keeps them on the minimal viable path — research-backed MCP server keeping LLMs aligned, reflective and safe.
# Try it (Claude-friendly) npx @pv-bhat/vibe-check-mcp start --stdio # Install to a client npx @pv-bhat/vibe-check-mcp install --client claude npx @pv-bhat/vibe-check-mcp install --client cursor npx @pv-bhat/vibe-check-mcp install --client windsurf npx @pv-bhat/vibe-check-mcp install --client vscode --config ./.vscode/mcp.json # Doctor npx @pv-bhat/vibe-check-mcp doctor
Requires Node >=20. These commands install straight from npm, build the CLI on demand, and work on any machine with npx.
Vibe Check MCP keeps agents on the minimal viable path and escalates complexity only when evidence demands it. Vibe Check MCP is a lightweight server implementing Anthropic's Model Context Protocol. It acts as an AI meta-mentor for your agents, interrupting pattern inertia with Chain-Pattern Interrupts (CPI) to prevent Reasoning Lock-In (RLI). Think of it as a rubber-duck debugger for LLMs – a quick sanity check before your agent goes down the wrong path.
Vibe Check MCP pairs a metacognitive signal layer with CPI so agents can pause when risk spikes. Vibe Check surfaces traits, uncertainty, and risk scores; CPI consumes those triggers and enforces an intervention policy before the agent resumes. See the CPI integration guide and the CPI repo at https://github.com/PV-Bhat/cpi for wiring details.
Vibe Check runs alongside your agent workflow, emitting signals that downstream overseers like CPI or human reviewers can act on. The high-level component map lives in docs/architecture.md, while the CPI handoff diagram and example shim are captured in docs/integrations/cpi.md.
Large language models can confidently follow flawed plans. Without an external nudge they may spiral into overengineering or misalignment. Vibe Check provides that nudge through short reflective pauses, improving reliability and safety.
| Feature | Description | Benefits |
|---|---|---|
| CPI Adaptive Interrupts | Phase-aware prompts that challenge assumptions | alignment, robustness |
| Multi-provider LLM | Gemini, OpenAI and OpenRouter support | flexibility |
| History Continuity | Summarizes prior advice when sessionId is supplied | context retention |
| Optional vibe_learn | Log mistakes and fixes for future reflection | self-improvement |
install --client now supports Cursor, Windsurf, and Visual Studio Code with idempotent merges, atomic writes, and .bak rollbacks.serverUrl entries for Windsurf and emit VS Code workspace snippets plus a vscode:mcp/install link when no config is provided.Use a lightweight “constitution” to enforce rules per sessionId that CPI will honor. Typical uses: “no external network calls,” “prefer unit tests before refactors,” “never write secrets to disk.”
API (tools):
update_constitution({ sessionId, rules }) → merges/sets rule set for the sessionreset_constitution({ sessionId }) → clears session rulescheck_constitution({ sessionId }) → returns effective rules for the session# Clone and install git clone https://github.com/PV-Bhat/vibe-check-mcp-server.git cd vibe-check-mcp-server npm ci npm run build npm test
Use npm for all workflows (npm ci, npm run build, npm test). This project targets Node >=20. If you see a TypeScript error about a duplicate require declaration when building with Node 20.19.3, ensure your dependencies are up to date (npm ci) or use the Docker setup below which handles the build automatically.
Create a .env file with the API keys you plan to use:
# Gemini (default) GEMINI_API_KEY=your_gemini_api_key # Optional providers OPENAI_API_KEY=your_openai_api_key OPENROUTER_API_KEY=your_openrouter_api_key # Optional overrides DEFAULT_LLM_PROVIDER=gemini DEFAULT_MODEL=gemini-2.5-pro
Start the server:
npm start
See docs/TESTING.md for instructions on how to run tests.
The repository includes a helper script for one-command setup. It builds the image, saves your GEMINI_API_KEY and configures the container to start automatically whenever you log in:
bash scripts/docker-setup.sh
This script:
~/vibe-check-mcp for persistent datadocker-compose.yml~/vibe-check-mcp/.envvibe-check-tcp-wrapper.sh which proxies Cursor IDE to the server
After running it, open Cursor IDE → Settings → MCP and add a new server of type Command pointing to:~/vibe-check-mcp/vibe-check-tcp-wrapper.sh
See Automatic Docker Setup for full details. If you prefer to run the commands manually:
docker build -t vibe-check-mcp . docker run -e GEMINI_API_KEY=your_gemini_api_key -p 3000:3000 vibe-check-mcp
Cut a new version by tagging the repository with semantic versioning (e.g., v2.6.0). The release workflow will:
npm ci and npm run build,npm run test:coverage,doctor, start --stdio --dry-run, start --http --port 2091 --dry-run, install --client claude --dry-run),NPM_TOKEN repository secret, andnpx @pv-bhat/vibe-check-mcp@<version> --help on the freshly released build.Ensure NPM_TOKEN is configured under Repository Settings → Secrets and variables → Actions before tagging.
Set whichever API key matches your provider — ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or OPENROUTER_API_KEY. The installer requires at least one of these when running with --non-interactive.
Secrets default to ~/.vibe-check/.env (created with 0600 permissions); pass --local to write to the current project's .env. Values are resolved in this order: shell environment → project .env → home config. The CLI never writes secrets to client config files – it references your environment instead.
The CLI supports stdio and HTTP transports. Transport resolution follows this order: explicit flags (--stdio/--http) → MCP_TRANSPORT → default stdio. When using HTTP, specify --port (or set MCP_HTTP_PORT); the default port is 2091. The generated entries add --stdio or --http --port <n> accordingly, and HTTP-capable clients also receive a http://127.0.0.1:<port> endpoint.
Each installer is idempotent and tags entries with "managedBy": "vibe-check-mcp-cli". Backups are written once per run before changes are applied, and merges are atomic (*.bak files make rollback easy). See docs/clients.md for deeper client-specific references.
claude_desktop_config.json (auto-discovered per platform).npx … start --stdio).vibe-check-mcp, the CLI leaves it untouched and prints a warning.~/.cursor/mcp.json (provide --config if you store it elsewhere).mcpServers layout.~/.codeium/windsurf/mcp_config.json, new builds use ~/.codeium/mcp_config.json.--http to emit an entry with serverUrl for Windsurf’s HTTP client.serverUrl entries are preserved and updated in place..vscode/mcp.json; profiles also store mcp.json in your VS Code user data directory.--config <path> to target a workspace file. Without --config, the CLI prints a JSON snippet and a vscode:mcp/install?... link you can open directly from the terminal.--dev-watch and/or --dev-debug <value> to populate dev.watch/dev.debug.*.bak next to your config) to revert immediately.vibe-check-mcp entry under mcpServers (Claude/Windsurf/Cursor) or servers (VS Code) as long as it is still tagged with "managedBy": "vibe-check-mcp-cli".CPI (Chain-Pattern Interrupt) is the research-backed oversight method behind Vibe Check. It injects brief, well-timed “pause points” at risk inflection moments to re-align the agent to the user’s true priority, preventing destructive cascades and reasoning lock-in (RLI). In pooled evaluation across 153 runs, CPI nearly doubles success (~27%→54%) and roughly halves harmful actions (~83%→42%). Optimal interrupt dosage is ~10–20% of steps. Vibe Check MCP implements CPI as an external mentor layer at test time.
Links:
import { vibe_check } from 'vibe-check-mcp'; const result = await vibe_check({ goal: 'Write unit tests', plan: 'Use vitest for coverage', sessionId: 'demo1' }); console.log(result.questions);
flowchart TD A[Agent Phase] --> B{Monitor Progress} B -- high risk --> C[CPI Interrupt] C --> D[Reflect & Adjust] B -- smooth --> E[Continue]
In your agent's system prompt, make it clear that vibe_check is a mandatory tool for reflection. Always pass the full user request and other relevant context. After correcting a mistake, you can optionally log it with vibe_learn to build a history for future analysis.
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. Optionally, record resolved issues with vibe_learn.
| Tool | Purpose |
|---|---|
| 🛑 vibe_check | Challenge assumptions and prevent tunnel vision |
| 🔄 vibe_learn | Capture mistakes, preferences, and successes |
| 🧰 update_constitution | Set/merge session rules the CPI layer will enforce |
| 🧹 reset_constitution | Clear rules for a session |
| 🔎 check_constitution | Inspect effective rules for a session |
This repository includes a CI-based security scan that runs on every pull request. It checks dependencies with npm audit and scans the source for risky patterns. See SECURITY.md for details and how to report issues.
GitHub issues, PulseMCP reviews, and Discord discussions keep surfacing the same needs: turn the validated research prototype into a dependable day-to-day tool, make the mentor's output easier to wire into automations, and provide lightweight guardrails so solo builders can adopt CPI without heavy lift.
vibe_check: Return a JSON envelope such as { advice, riskScore, traits } so downstream agents can reason deterministically while preserving readable reflections.taskContext.generateResponse in src/utils/llm.ts with retries and exponential backoff, with a follow-up circuit breaker once the basics land.src/index.ts to mitigate prompt-injection vectors.src/utils/state.ts and switch src/utils/storage.ts file writes to fs.promises to avoid blocking the event loop.These initiatives are tracked as community-facing GitHub issues so contributors can grab them and see progress in the open.
docs/ examples compile (e.g., TypeScript snippet type-check) to catch drift between docs and code.--help example aligned with the refreshed prompt guidance.docs/agent-prompting.md and docs/technical-reference.md from the README section headers to reduce context switching for new contributors.Contributions are welcome! See CONTRIBUTING.md.
vibe_learn is optional.Vibe Check MCP is released under the MIT License. Built for reliable, enterprise-ready AI agents.
Vibe Check MCP created by: Pruthvi Bhat, Initiative - https://murst.org/