VibeWise MCP

Universal MCP port of VibeWise, a Claude Code plugin that puts learning and design first.

One gate for every MCP-capable coding agent: Claude Code, Cursor, Codex CLI, Antigravity, and others:

• The agent asks your approach before building; you shape the design.
• Your decisions and the project map are recorded locally in .vibe-wise/.
• Code is written only after you approve an implementation checkpoint (vibe_confirm).
• No account, backend, or telemetry. Notes are local Markdown.

How the gate works

you describe the task
        │
        ▼
Build checkpoint ── agent asks how YOU would approach it ── your reasoning recorded
        │
        ▼
Design checkpoint ── proposal + tradeoffs ── "Confirm and continue" records it (no code)
        │
        ▼
Implementation checkpoint ── exact code changes ── "Implement this step" authorizes code
        │
        ▼
agent writes code, runs checks, gives an Implementation report

The three checkpoints are not mandatory stops; when the design is already clear the Implementation checkpoint confirms it too. The pending decision lives in .vibe-wise/progress.md, survives restarts and compaction, and is the ledger the tools read and write: restarting a session is never approval.

Tools

Tool	Purpose
vibe_status	Check the gate: active, stage, pending decision, what to do next
vibe_start	Activate learning mode; create .vibe-wise/; onboard or resume
vibe_onboard_answer	Record one onboarding answer; get the next question
vibe_checkpoint	Open build / design / implement checkpoint
vibe_confirm	Record the user's decision: confirm / discuss / approach
vibe_report	Record the implementation report after approved coding
vibe_map_update	Update the evidence-based project map
vibe_pause	Pause / resume the gate ("Learning mode: paused")
vibe_reset	Preview + token-confirmed reset with automatic backup
vibe_read_notes	Read all notes + parsed gate state (session restoration)

State (.vibe-wise/ in your project)

.vibe-wise/
  profile.md        learner profile, preferences, "Learning mode: active/paused"
  progress.md       learning events + "## Pending decision" (the gate ledger)
  project-map.md    evidence-based system map, confirmed designs, approved work
  backups/          automatic backups created by vibe_reset

Add .vibe-wise/ to .gitignore if you don't want the notes in Git; the server never edits .gitignore silently.

Install

Requires Node.js 20+. Build once:

npm install && npm run build

Claude Code

claude mcp add vibe-wise -- node /absolute/path/to/vibe-wise-mcp/dist/server.js

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "vibe-wise": { "command": "node", "args": ["/absolute/path/to/vibe-wise-mcp/dist/server.js"] }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.vibe-wise]
command = "node"
args = ["/absolute/path/to/vibe-wise-mcp/dist/server.js"]

Antigravity (agy)

~/.gemini/settings.json (or the Antigravity MCP settings file):

{
  "mcpServers": {
    "vibe-wise": { "command": "node", "args": ["/absolute/path/to/vibe-wise-mcp/dist/server.js"] }
  }
}

Generic MCP client

Command: node <repo>/dist/server.js, stdio transport, no env vars needed.

Usage

In any agent, after installing the server:

1. Please run vibe_status, then vibe_start for this project (one-time setup).
2. Then just ask for what you want built. The agent opens a Build checkpoint and asks for your approach before writing anything.
3. Say "pause learning" anytime; resume with vibe_start (action=resume).
4. "Reset learning" restarts onboarding; the previous notes are backed up first.

The server exposes its behavior guide as an MCP resource (vibewise://guides/behavior); agents that read resources get the full teaching contract, others get it through tool guidance.

Development

npm run build   # tsc -> dist/
npm test        # node:test unit/behavior tests (dist/test/*.test.js)
node src/test/smoke.mjs   # end-to-end MCP protocol smoke test over stdio

Port of VibeWise by nykooi1 (MIT). State format and teaching behavior follow the original plugin; enforcement moved from prompts to the tool layer.

License

MIT, see LICENSE.