Skip to main content
Glama

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.

Related MCP server: piia-engram

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.

Available Tools

10 tools
vibe_checkpointA

VibeWise: open a checkpoint BEFORE doing the work. kind=build: ask how the USER would approach the problem (their reasoning first, never your design). kind=design: present the agreed design + tradeoffs for confirmation. kind=implement: present the exact code changes for approval - the only gate that authorizes writing code.

Inputs: kind (required), name (required), proposal, projectPath, +2 more.

vibe_confirmA

VibeWise: resolve the open checkpoint with the USER's decision. option=confirm for 'Confirm and continue' (design) or 'Implement this step' (implement); option=discuss when they asked questions; option=approach + userText to record the user's own build-stage reasoning. Without this tool's record, code must not be written.

Inputs: option (required), userText, projectPath.

vibe_map_updateC

VibeWise: update the evidence-based project map (purpose, components, flow, boundaries, unknowns). Mark unknowns as unknown.

Inputs: purpose, mainFlow, unknowns, components, +4 more.

vibe_onboard_answerB

VibeWise: record one onboarding answer from the user and get the next question. Never answer these yourself.

Inputs: field (required), value (required), projectPath, questionStyle, +2 more.

vibe_pauseB

VibeWise: pause learning mode (gate off) at the user's request, or resume it.

Inputs: resume, projectPath.

vibe_read_notesB

VibeWise: read all learning notes (.vibe-wise/*.md) plus the parsed gate state. Use for session restoration and compaction recovery; search ALL of progress.md for pending decisions.

Inputs: projectPath.

vibe_reportA

VibeWise: record the implementation report after approved coding: what changed, how it works, why it fits the design, and real verification results.

Inputs: summary (required), projectPath, verification.

vibe_resetA

VibeWise: restart learning from scratch. Call without confirm for a preview token; back up + reset only after the user explicitly confirms, passing the token back.

Inputs: confirm, projectPath.

vibe_startB

VibeWise: activate learning-first mode (creates .vibe-wise/, runs onboarding one question at a time, or resumes a paused/pending state). Call before the first build task.

Inputs: action, projectPath.

vibe_statusA

VibeWise: check the learning gate for this project - active mode, current checkpoint stage, pending decision, and what you must do next. Call this before starting any coding work and whenever unsure whether coding is allowed.

Inputs: projectPath.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools map to distinct lifecycle stages (start, checkpoint, confirm, report, reset), but vibe_status and vibe_read_notes both surface gate/state info, and vibe_pause's 'resume' overlaps with vibe_start's 'resumes a paused/pending state'. Descriptions mostly disambiguate these, so confusion risk is low.

    Naming Consistency5/5

    Every tool uses the same vibe_ prefix with a consistent snake_case noun/verb (vibe_status, vibe_start, vibe_checkpoint, vibe_map_update). No camelCase or mixed conventions, so the pattern is fully predictable.

    Tool Count5/5

    10 tools is well within the ideal 3-15 range and each corresponds to a distinct step of the learning-gate workflow. No tool feels redundant or filler.

    Completeness4/5

    The surface covers the full learning lifecycle: activation, onboarding, checkpoints, confirmation, reporting, map maintenance, pause/resume, reset, and state reading. Minor gap: no explicit way to answer/close an onboarding session or query individual notes, but agents can work around these.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Adds a human-in-the-loop checkpoint to MCP-capable AI coding agents, enabling them to pause and request user feedback before executing actions.
      16 npm
      72
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP-compatible coding tools to start from one portable, local-first identity and knowledge layer containing the user's approved preferences, quality standards, lessons, decisions, and project context. It stores this in local files the user owns and can inspect, edit, or override, with governance over AI-proposed writes and no cloud account required.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP-compatible coding agents to start from one portable, local-first identity and long-term knowledge layer, so preferences, quality bars, lessons, decisions, and project context carry across tools instead of being relearned per session. Everything the AI writes stays in local files the user can inspect, edit, approve, or override.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables a local-first, user-owned AI work identity layer that lets multiple MCP coding tools share approved preferences, quality standards, lessons, decisions, and project context, with local files you can inspect, edit, and override.
      -