You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This project adheres to the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) Code of Conduct. By participating, you are expected to uphold this code.
4
+
5
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the maintainer listed in `package.json`.
VibeCheck MCP is a lightweight server implementing Anthropic's [Model Context Protocol](https://anthropic.com/mcp). It acts as an **AI meta-mentor** for your agents, interrupting pattern inertia with **Critical Path 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.
44
+
45
+
## The Problem: Pattern Inertia & Reasoning Lock-In
46
+
47
+
Large language models can confidently follow flawed plans. Without an external nudge they may spiral into overengineering or misalignment. VibeCheck provides that nudge through short reflective pauses, improving reliability and safety.
33
48
34
49
## Key Features
35
50
36
-
-**vibe_check** – Adaptive meta-mentor step that questions plans and highlights unstated assumptions.
37
-
-**vibe_learn** – Optional log of mistakes and solutions to gradually improve over time.
38
-
-**History continuity** – Prior feedback is automatically provided for a sense of memory.
39
-
-**Multi-LLM flexibility** – Choose Gemini, OpenAI or OpenRouter by overriding two fields.
40
-
41
-
## What's New in v2.1
42
-
43
-
- Meta-mentor prompt rewritten for methodology-focused guidance.
44
-
- History continuity enabled by default for richer conversations.
45
-
- Multi-provider support (Gemini, OpenAI, OpenRouter) with simple overrides.
46
-
-`vibe_learn` made optional for privacy-conscious deployments.
47
-
- Repository restructured with Vitest unit tests and CI workflow.
This project targets Node **20+**. If you see a TypeScript error about a
63
-
duplicate `require` declaration when building with Node 20.19.3, ensure your
64
-
dependencies are up to date (`npm install`) or use the Docker setup below which
65
-
handles the build automatically.
72
+
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 install`) or use the Docker setup below which handles the build automatically.
66
73
67
74
Create a `.env` file with the API keys you plan to use:
See [docs/TESTING.md](./docs/TESTING.md) for instructions on how to run tests.
87
90
88
91
### Docker
89
-
90
-
The repository includes a helper script for one-command setup. It builds the
91
-
image, saves your `GEMINI_API_KEY` and configures the container to start
92
-
automatically whenever you log in:
93
-
92
+
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:
94
93
```bash
95
94
bash scripts/docker-setup.sh
96
95
```
97
-
98
96
This script:
99
-
100
97
- Creates `~/vibe-check-mcp` for persistent data
101
98
- Builds the Docker image and sets up `docker-compose.yml`
102
99
- Prompts for your API key and writes `~/vibe-check-mcp/.env`
103
-
- Installs a systemd service (Linux) or LaunchAgent (macOS) so the container
104
-
starts at login
100
+
- Installs a systemd service (Linux) or LaunchAgent (macOS) so the container starts at login
105
101
- Generates `vibe-check-tcp-wrapper.sh` which proxies Cursor IDE to the server
106
-
107
-
After running it, open Cursor IDE → **Settings** → **MCP** and add a new server
108
-
of type **Command** pointing to:
109
-
102
+
After running it, open Cursor IDE → **Settings** → **MCP** and add a new server of type **Command** pointing to:
110
103
```bash
111
104
~/vibe-check-mcp/vibe-check-tcp-wrapper.sh
112
105
```
113
-
114
106
See [Automatic Docker Setup](./docs/docker-automation.md) for full details.
115
-
116
107
If you prefer to run the commands manually:
117
-
118
108
```bash
119
109
docker build -t vibe-check-mcp .
120
110
docker run -e GEMINI_API_KEY=your_gemini_api_key -p 3000:3000 vibe-check-mcp
121
111
```
122
112
123
113
### Integrating with Claude Desktop
124
-
125
114
Add to `claude_desktop_config.json`:
126
-
127
115
```json
128
116
"vibe-check": {
129
117
"command": "node",
@@ -132,12 +120,33 @@ Add to `claude_desktop_config.json`:
132
120
}
133
121
```
134
122
135
-
## Agent Prompting Essentials
123
+
## Usage Examples
124
+
```ts
125
+
import { vibe_check } from'vibe-check-mcp';
126
+
const result =awaitvibe_check({
127
+
goal: 'Write unit tests',
128
+
plan: 'Use vitest for coverage',
129
+
sessionId: 'demo1'
130
+
});
131
+
console.log(result.questions);
132
+
```
133
+
```mermaid
134
+
flowchart TD
135
+
A[Agent Phase] --> B{Monitor Progress}
136
+
B -- high risk --> C[CPI Interrupt]
137
+
C --> D[Reflect & Adjust]
138
+
B -- smooth --> E[Continue]
139
+
```
140
+
141
+
## Adaptive Metacognitive Interrupts (CPI)
142
+
<details><summary>Advanced CPI Details</summary>
143
+
The CPI architecture monitors planning, implementation and review phases. When uncertainty spikes, VibeCheck pauses execution, poses clarifying questions and resumes once the agent acknowledges the feedback.
144
+
</details>
136
145
146
+
## Agent Prompting Essentials
137
147
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.
138
148
139
149
Example snippet:
140
-
141
150
```
142
151
As an autonomous agent you will:
143
152
1. Call vibe_check after planning and before major actions.
@@ -146,14 +155,12 @@ As an autonomous agent you will:
146
155
```
147
156
148
157
## When to Use Each Tool
149
-
150
158
| Tool | Purpose |
151
159
|------|---------|
152
160
| 🛑 **vibe_check**| Challenge assumptions and prevent tunnel vision |
153
161
| 🔄 **vibe_learn**| Capture mistakes, preferences and successes |
@@ -162,24 +169,26 @@ As an autonomous agent you will:
162
169
-[Case Studies](./docs/case-studies.md)
163
170
-[Changelog](./docs/changelog.md)
164
171
165
-
## Security
166
-
167
-
This repository includes a CI-based security scan that runs on every pull request.
168
-
It checks dependencies with `npm audit` and scans the source for risky patterns.
169
-
See [SECURITY.md](./SECURITY.md) for details and how to report issues.
170
-
171
-
## To-do List
172
+
## Research & Philosophy
173
+
See [docs/philosophy.md](./docs/philosophy.md) for the alignment research behind VibeCheck. The approach draws inspiration from Reflexion, Constitutional AI and other high-trust frameworks.
172
174
173
-
-[x] Additional examples for OpenRouter models
174
-
-[x] Repomix access to pass repositories to VC
175
-
-[x] Agents.md addendum to improve plug-and-play integration
175
+
## Security
176
+
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](./SECURITY.md) for details and how to report issues.
176
177
177
-
## Contributing
178
+
## Roadmap
179
+
1. Benchmarks and latency profiling
180
+
2. Adaptive tuning based on agent performance
181
+
3. Multi-agent cooperation support
182
+
4. Optional human-in-the-loop review
178
183
179
-
Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md).
184
+
## Contributing & Community
185
+
Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) and join our Discord for discussion.
180
186
181
-
## 🔗 Find **VibeCheck MCP** on:
187
+
## FAQ
188
+
-**Does it increase latency?** A single CPI call typically adds ~1 second depending on the provider.
189
+
-**Can I disable logging?** Yes, `vibe_learn` is optional.
Copy file name to clipboardExpand all lines: docs/advanced-integration.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Advanced Integration Techniques
2
2
3
-
For optimal metacognitive oversight, these advanced integration strategies leverage the full power of Vibe Check as a pattern interrupt system, recalibration mechanism, and self-improving feedback loop. Starting with v2.1, previous vibe_check output is automatically summarized and fed back into subsequent calls, so a `sessionId` is recommended for continuity.
3
+
For optimal metacognitive oversight, these advanced integration strategies leverage the full power of Vibe Check as a pattern interrupt system, recalibration mechanism, and self-improving feedback loop. Starting with v2.2, previous vibe_check output is automatically summarized and fed back into subsequent calls, so a `sessionId` is recommended for continuity.
Copy file name to clipboardExpand all lines: docs/agent-prompting.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Agent Prompting Strategies
2
2
3
-
Effective agent-oversight relationships require careful prompting to ensure that AI agents properly respect and integrate feedback from Vibe Check. In v2.1 the tool acts more like a collaborative debugger than a strict critic. Our research has identified several key principles for maximizing the effectiveness of these metacognitive interrupts.
3
+
Effective agent-oversight relationships require careful prompting to ensure that AI agents properly respect and integrate feedback from Vibe Check. In v2.2 the tool acts more like a collaborative debugger than a strict critic. Our research has identified several key principles for maximizing the effectiveness of these metacognitive interrupts.
These short descriptions can be used when submitting VibeCheck MCP to external registries or directories.
4
+
5
+
## Smithery.ai
6
+
```
7
+
Metacognitive oversight MCP server for AI agents – adaptive CPI interrupts for alignment and safety.
8
+
```
9
+
10
+
## Glama Directory
11
+
```
12
+
Metacognitive layer for Llama-compatible agents via MCP. Enhances reflection, accountability and robustness.
13
+
```
14
+
15
+
## Awesome MCP Lists PR Draft
16
+
```
17
+
- [VibeCheck MCP](https://github.com/PV-Bhat/vibe-check-mcp-server) - Adaptive sanity check server preventing cascading errors in AI agents.
0 commit comments