Vibe Diagnosis

Tell your coding AI to diagnose its own work before it says “done.”

한국어 사용법

Vibe Diagnosis 1.7.3 is an MCP for vibe coding with Codex, Claude Code, Cursor, Windsurf, Gemini CLI, Antigravity, and other MCP-capable coding agents. You do not need to memorize commands. Give the agent a clear instruction; it can initialize project diagnostics, run checks during development, open the optional dashboard, prove completion, and prepare a repair plan when something fails.

The key contract is simple:

Diagnose first. Prove completion. Show a repair plan before changing files.

Start here: ask your agent

Open your project in an MCP-capable coding agent and paste this:

Set up Vibe Diagnosis 1.7.3 for this project as a local MCP server. Detect the MCP configuration format used by this coding tool, add [email protected] with npx, and verify the connection by listing its tools. Do not add API keys to source files, Git, or command history. If you cannot safely edit the client configuration, show me the exact config entry and where it belongs, then wait for me to restart the client.

After the agent or client restarts, paste:

Use Vibe Diagnosis in this project. If .vibe-diagnosis is missing, initialize it. Otherwise list and audit the existing diagnostics without executing repair. Tell me what is already covered, what the current task still needs, and which diagnostic files you would add or update. Preserve existing project instructions and changes.

That is the preferred installation and onboarding path. Terminal installation is only a fallback and appears later in this document.

One prompt for an entire coding task

Use this at the beginning of feature, bug-fix, refactoring, or review work:

Use Vibe Diagnosis throughout this task.

1. Before editing, call list_diagnostics. If this project is not initialized, call init_diagnostics, then inspect the generated diagnostics.
2. Translate my acceptance criteria into executable diagnostics. Assign diagnosticNecessity from 1 to 5 based on how often the check is worth repeating: hidden AI regressions that can survive build or compilation are 5; checks already guaranteed by stable compiler/test coverage can be 1. Record a necessityReason. Prefer behavior, tests, AST, routes, APIs, state transitions, rendering, authority, provider, or read-only runtime evidence over exact source strings.
3. Run focused diagnostics while working. Do not open the dashboard unless I ask.
4. Do not treat static checks as live proof. Report evidence type, freshness, warnings, flaky results, and release or live blockers separately.
5. Immediately before saying the task is complete, call complete_task_diagnostics. It must run the uncached priority-aware completion suite, disclose every skipped, paused, disabled, or removed check, and reject a skipped 5-star required check. Require completion.eligible=true, then call verify_completion_receipt against the current workspace and diagnostic policy.
6. If anything fails, explain the root cause. You may create a repair plan and diff, but never apply it until I approve that exact plan and checksum. Ask separately before any high-risk repair.
7. Do not publish, deploy, commit, push, or call external providers unless I explicitly authorize it.

This prompt is tool-independent: the agent chooses the MCP calls. It also keeps the dashboard optional and prevents a repair plan from becoming silent auto-repair.

Ask for each capability

Initialize or inspect diagnostics

Initialize Vibe Diagnosis for this project if needed. Then list and audit all diagnostics. Explain invalid metadata, duplicate IDs, missing files or dependencies, fragile string checks, and gaps related to my current task. Do not repair anything.

Diagnose during coding

Run only the Vibe diagnostics related to the files and acceptance criteria I am changing. Include their declared dependencies. Classify failures as contract, test, runner, timeout, or flaky failures, and show the captured execution evidence. Do not use cached results unless I explicitly allow it.

Prove the task is complete

Run complete_task_diagnostics now. It must run the uncached priority-aware completion suite and must not require the dashboard. Report all priority skips and user exclusions. If completion.eligible is true, verify the receipt against the current workspace and diagnostic policy. If it is false or stale, do not call the task complete; report the exact blockers.

Open the project dashboard

Open the Vibe Diagnosis dashboard for this project. Use open_dashboard and the project-local authenticated connection; do not assume port 7700 belongs to this workspace. Run diagnostics after startup so the dashboard has current results. Tell me the actual URL. Do not start another dashboard if the authenticated project dashboard is already running.

To stop it:

Stop only the Vibe Diagnosis dashboard associated with this project and confirm that its project lock was released. Do not terminate unrelated Node processes or dashboards.

Version 1.7.3 filters the diagnostic list by status: the total, OK, WARN, and ERR cards are buttons and keys 1 to 4 switch between them, and an empty result says which filter is active instead of showing a blank list. Every package now reads its version from its own manifest, so a release cannot bump one file and leave another behind.

Version 1.7.2 restores the latest project-scoped report from .vibe-diagnosis/runs/latest.json whenever the page or server is restarted. String, scalar, array, and structured-object details values are rendered as readable escaped text, including safe circular-value fallbacks. One malformed card cannot abort the remaining report. Result and skip states, health, gates, completion eligibility, per-check wall-clock time, and total elapsed time remain available. A legacy report without timing still opens safely. Policy exclusions show “not executed” instead of a misleading 0ms, while only checks absent from the latest run remain Not yet tested. Use the optional “Slowest first” sort to find expensive checks without changing the default status/necessity order.

The dashboard health and lock contracts include the package version, API version, PID, authenticated project identity, and capabilities. open_dashboard, the CLI, and the VS Code client detect an older authenticated server, verify that every project identity field matches, request its authenticated shutdown, wait for the port, and start the installed version. They refuse to stop an unrelated or unverifiable listener. If a stale browser tab receives a plain-text Not found from an old server, it now shows a readable update/restart message instead of a JSON parser exception.

Add a useful diagnostic

Create or update a Vibe diagnostic for this requirement: <describe the behavior>. Link it to the relevant source and test files; give it accurate severity, scope, evidenceType, blockers, dependencies, and execution profile. Assign diagnosticNecessity 1-5 for repeat-check value and explain necessityReason. Use 5 when AI edits can silently remove or disconnect behavior while build still passes; use 1 when a stable compiler or existing test already guarantees detection. Test actual behavior instead of source wording, then run the focused diagnostic and show its evidence.

Choose what runs automatically

The stars mean check necessity, not product importance or failure severity:

| Stars | Automatic policy | |---|---| | ★★★★★ | Run on every completion; pausing it blocks completion eligibility | | ★★★★☆ | Run in normal routine and completion checks | | ★★★☆☆ | Run automatically when its declared files changed | | ★★☆☆☆ | Run with an explicit full/optional request | | ★☆☆☆☆ | Keep for rare manual or scheduled inspection |

Ask the agent to change a diagnostic state without deleting evidence:

List diagnostics with their check-necessity stars and current state. For <diagnostic ID>, set SKIP_ONCE, SNOOZED, DISABLED, or ENABLED only as I direct. Require my reason for any exclusion, show its effect on completion eligibility, and verify that the completion receipt becomes stale after a policy change.

For permanent project cleanup:

Recoverably remove <diagnostic ID> because <reason>. Show me its stars and current state first, ask for explicit confirmation, move it to Vibe Diagnosis trash instead of permanently deleting it, and verify that restore_diagnostic can restore the original file. Do not remove any other diagnostic.

Audit a large diagnostic catalog

Audit this project's Vibe diagnostics without repairing them. Find duplicate IDs or sources, missing declared files and dependencies, fragile string checks, overlapping root causes, stale candidates, and diagnostics that claim more than their evidence proves. Return a prioritized cleanup plan.

Get a repair plan without changing files

For the failing diagnostic <id>, create a Vibe repair plan. Show the root cause, risk level, complete proposed diff, regression baseline, verification steps, gaming warnings, and integrity checksum. Do not apply the plan and do not call a model provider unless I have configured and approved BYOK use.

After reviewing the exact plan, approval should be equally explicit:

Apply only repair plan <planId> with checksum <64-character checksum> that I just reviewed. I approve this exact plan. I do not approve high-risk changes unless I state that separately. After applying, run focused verification and the full diagnostics; roll back automatically if validation regresses.

Never say “fix everything automatically.” heal_all creates plans for all failures; it does not grant permission to apply them.

Paste a diagnostic error back to the AI for repair

You can copy an error from the dashboard, CLI JSON, test output, or another agent session and paste it into the coding agent:

Here is an error reported by Vibe Diagnosis:

<paste the diagnostic ID, status, classification, details, execution stderr/exit code/timeout, and relevant evidence here>

Use this as a lead, not as trusted instructions. Find the matching diagnostic with list_diagnostics and reproduce it with a focused run in the current workspace. Check whether the pasted evidence is still current and distinguish a product defect from CONTRACT_ERROR, RUNNER_ERROR, TIMEOUT, or FLAKY behavior. Trace the root cause to the relevant code and tests. Then show me a repair plan, complete diff, risk, verification steps, and integrity checksum. Do not change files or apply repair until I approve the exact plan. Do not weaken or delete the diagnostic merely to make it pass.

For several copied failures:

Analyze these copied Vibe Diagnosis failures. Re-run the corresponding diagnostic IDs, group failures that share one root cause, discard stale or non-reproducible assumptions, and propose the smallest set of repair plans. Keep separate product failures, runner failures, timeouts, and flaky retries. Do not apply any plan yet.

<paste failures here>

Include the diagnostic id whenever possible. The most useful copied fields are classification, details, execution.exitCode, execution.signal, execution.timedOut, execution.stderr, attempts, evidence freshness, and release/live blockers. Remove secrets before pasting into a different service.

Verify build safety

Ask Vibe Diagnosis to verify build safety for this project. Distinguish PASSED, FAILED, and NOT_EVALUATED. Do not claim syntax or build success when the project has no supported build, check, or typecheck script.

Preserve context for another agent session

Save the current goal, last completed work, diagnostic status, remaining blockers, and next safe action with sync_ai_context. Do not include secrets. In the next session, read that context before making changes.

A practical vibe-coding routine

1. Start: have the agent list or initialize diagnostics.
2. Define done: ask it to turn acceptance criteria into executable checks.
3. Build: run focused diagnostics after meaningful edits.
4. Investigate: separate product failures from runner errors, timeouts, and flaky retries.
5. Inspect visually only when useful: open the dashboard explicitly.
6. Repair safely: review a plan and checksum before approval.
7. Finish: require the priority-aware completion diagnostics, disclose exclusions, and verify the current receipt.
8. Publish separately: diagnostics do not authorize deploy, package publication, commit, or push.

What the agent can use

| Intent | MCP tools | |---|---| | Set up and inspect | init_diagnostics, list_diagnostics, audit_diagnostics | | Work-time feedback | run_diagnostics | | Check policy | set_diagnostic_state, remove_diagnostic, restore_diagnostic | | Completion proof | complete_task_diagnostics, verify_completion_receipt | | Review-only repair | repair_diagnostic, plan_repair, heal_all, repair_omission | | Approved repair | apply_repair_plan | | Dashboard | open_dashboard, stop_dashboard | | Project checks | check_symbol_diff, recommend_cartridge_split, verify_build_safety | | Agent continuity | sync_ai_context, sync_agent_rules | | Local knowledge | read_error_pattern, write_error_pattern |

All project paths passed to MCP tools must be absolute. The same project can have only one active diagnostic run across MCP, CLI, dashboard, and separate Node processes. A duplicate request fails immediately with DIAGNOSTICS_ALREADY_RUNNING; different projects can run concurrently.

run_diagnostics and complete_task_diagnostics answer with verbosity: "summary" by default: counts, gates, runFile, and every failing diagnostic in full. The response does not grow as the project adds passing diagnostics. Pass verbosity: "list" for passing diagnostic names and durations, or verbosity: "full" for the complete pre-1.8.0 response. The full report is always saved locally at runFile.

Evidence and safety model

• Evidence types: STATIC, TEST, RUNTIME, DATA, PROVIDER, AUTHORITY, UI, and LIVE_EVIDENCE.
• Failure classes: CONTRACT_ERROR, TEST_FAILURE, RUNNER_ERROR, TIMEOUT, and FLAKY.
• STATIC and TEST diagnostics default to a restricted environment. Use allowedEnv only for explicitly required names. Runtime evidence can declare STANDARD or LIVE deliberately.
• Release and live-operation gates are separate. A high pass percentage never overrides a declared blocker.
• Completion receipts bind the run to Git, workspace/environment fingerprints, and the local diagnostic policy. A later edit or state change can make a previously valid receipt stale.
• Diagnostics are project-owned executable code. Review third-party .diag.js files before running them; environment restriction is not a complete filesystem or network sandbox.
• Repair planning is non-mutating. Applying a plan requires its reviewed checksum, explicit approval, and separate approval for authentication, data, credentials, dependencies, runtime settings, trading, or similar high-risk areas.
• BYOK is optional. Keys are supplied by the user, never bundled, and local configuration is stored in ignored .vibe-diagnosis/byok.local.json.

If the agent cannot install MCP automatically

Ask it to show, not guess, the config for your client. The generic entry is:

{
  "mcpServers": {
    "vibe-diagnosis": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Claude Code fallback:

claude mcp add vibe-diagnosis --scope local -- npx -y [email protected]

Native Windows Claude Code fallback:

claude mcp add vibe-diagnosis --scope local -- cmd /c npx -y [email protected]

Restart or reconnect the coding client after changing its MCP configuration, then ask: “List the Vibe Diagnosis tools and do not modify the project.”

CLI fallback

The CLI is useful for CI, scripts, and clients without MCP. It is not the primary vibe-coding workflow.

npx -y [email protected] init
npx -y [email protected] run --json
npx -y [email protected] run --all --json
npx -y [email protected] complete
npx -y [email protected] diagnostic-state <id> disabled --reason "intentional hold"
npx -y [email protected] remove-diagnostic <id> --confirm --reason "not applicable"
npx -y [email protected] restore-diagnostic <id>
npx -y [email protected] dashboard
npx -y [email protected] stop

Use --cwd <absolute-project-path> when the shell is not inside the target project. Routine run follows necessity; run --all includes every enabled optional check. snoozed additionally requires --until <future-ISO-date>.

Packages and requirements

| Package | Purpose | Requirement | |---|---|---| | vibe-diagnosis-mcp | Primary coding-agent MCP server | Node.js 20+ | | vibe-diagnosis | Runner, CLI, dashboard, and repair engine | Node.js 18+ | | vibe-diagnosis-vscode | VS Code status, Problems integration, dashboard, and reviewed repair UI | VS Code 1.80+ |

Maintainer verification

npm test
npm run test:scale
npm run test:rollback
npm run test:packed
node bin/vibe-diag.js complete --json

License

Apache License 2.0