vibesplainSAFE
Static-analysis MRI for codebases — a Tree-Sitter dossier engine + deterministic PreToolUse safety gate for AI coding agents. Zero LLM calls, zero API keys.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
◈ vibesplain Give your AI agent an architectural map of any codebase.
Install · Usage · MCP Tools · How It Works · Development
vibesplain is an MCP server that scans a codebase with Tree-Sitter, scores every file by importance and complexity, and produces an Architectural Dossier — a structured set of decision cards your agent writes after analyzing the code.
The output is a self-contained HTML file you can open in any browser.
Zero LLM calls. Zero API keys. Zero network. Pure static analysis.
Install
npx vibe-splain install
This patches your coding agent's config to register vibesplain as an MCP server. Restart your agent afterward.
Usage
Once installed, open a project in your agent and run the built-in prompt:
Claude Code / Gemini CLI:
/prompt build_dossier
Cursor / Windsurf: Select the build_dossier prompt from the vibesplain MCP panel.
Your agent will:
- Scan the project and rank files by architectural importance
- Read each high-importance file in depth
- Write a Decision Card for each — thesis, blast radius, evidence, optional diagram
- Return a
file://link to the Dossier UI
Open the link. Done.
MCP Tools
The build_dossier prompt orchestrates these tools automatically. You can also call them manually.
0cd283b0f59eOBSERVED · 2026-10-11Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add ui -- npx -y @vibesplain/[email protected]
{
"mcpServers": {
"ui": {
"command": "npx",
"args": [
"-y",
"@vibesplain/[email protected]"
]
}
}
}Exposed tools (6)
5 read · 1 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
Core | read | Primary application code. |
build_dossier | read | Build a full architectural dossier using vibesplain (replaces the need to copy-paste the README prompt) |
get_strategic_overview | write | Returns the current state of the dossier without evidence snippets (to save tokens). Use this to see what has already been analyzed and what is stale. Check stalePaths to know which files need re-analysis. |
get_wild_discoveries | read | Returns Decision Cards that are both high-heat (heat ≥ 60) AND/OR high-severity (severity ≥ 4) — the files that are load-bearing AND smelly. These are the highest-leverage things to understand and fix first. |
inspect_pillar | read | Returns all Decision Cards for a specific pillar including full evidence snippets. Use when you need deep detail on a specific area of the codebase. |
mark_stale | read | Manually marks Decision Cards as stale when you detect a file has changed. The file watcher does this automatically, but call this if you modify a file yourself during a session. |
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (5 observation(s))
- Network
- none-observed
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (8)
} from '../../signals.js';
const local = join(__dirname, '../../wasm', file);
import { ExportOrchestrator } from '../../export/ExportOrchestrator.js';import { ExportOrchestrator } from '../../export/ExportOrchestrator.js';import { startWatcher } from '../../export/Watcher.js';web-tree-sitter, tree-sitter-wasms, uuid, @types/uuid, typescript
@modelcontextprotocol/sdk, chokidar, commander, fs-extra, tar, tree-sitter-wasms, web-tree-sitter, uuid
mermaid, react, react-dom, shiki, @types/react, @types/react-dom, @vitejs/plugin-react, typescript
Gates applied: no_behavioural_pass.
0cd283b0f59efull audit observations/trust-audit/mcp-server/abp2204__vibesplain.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-11 | 0cd283b0f59e | SAFE | B | 89 | first audit |
Questions
What is the vibesplain MCP server?
Static-analysis MRI for codebases — a Tree-Sitter dossier engine + deterministic PreToolUse safety gate for AI coding agents. Zero LLM calls, zero API keys.
What tools does vibesplain expose?
6 in total: 5 read-only, 1 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is vibesplain safe to connect to an agent?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean server reads B.
What credentials does vibesplain need?
No credential environment variables were found in its source, so it appears to need none.
How does vibesplain run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as @vibesplain/ui at 1.2.2.
How current is this page?
The grade is for one exact copy of the source (0cd283b0f59e), read on 2026-10-11. The repository is watched and re-audited when it changes.