\n ◈ vibesplain
\n Give your AI agent an architectural map of any codebase.\n
\n Install ·\n Usage ·\n MCP Tools ·\n How It Works ·\n Development\n
\n\n---\n\n**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.\n\nThe output is a self-contained HTML file you can open in any browser.\n\n**Zero LLM calls. Zero API keys. Zero network. Pure static analysis.**\n\n---\n\n## Install\n\n```bash\nnpx vibe-splain install\n```\n\nThis patches your coding agent's config to register vibesplain as an MCP server. Restart your agent afterward.\n\n| Agent | Config patched |\n|-------|---------------|\n| Claude Code | `~/.claude/settings.json` |\n| Claude Desktop | `~/.claude/claude_desktop_config.json` |\n| Gemini CLI | `~/.gemini/settings.json` |\n| Cursor | `~/.cursor/mcp.json` |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` |\n\n---\n\n## Usage\n\nOnce installed, open a project in your agent and run the built-in prompt:\n\n**Claude Code / Gemini CLI:**\n```\n/prompt build_dossier\n```\n\n**Cursor / Windsurf:** Select the `build_dossier` prompt from the vibesplain MCP panel.\n\nYour agent will:\n1. Scan the project and rank files by architectural importance\n2. Read each high-importance file in depth\n3. Write a **Decision Card** for each — thesis, blast radius, evidence, optional diagram\n4. Return a `file://` link to the Dossier UI\n\nOpen the link. Done.\n\n---\n\n## MCP Tools\n\nThe `build_dossier` prompt orchestrates these tools automatically. You can also call them manually.\n\n| Tool | What it does |\n|------|-------------|\n| `scan_project` | Scans the repo. Returns ranked files grouped by architectural pillar. Call this first. |\n| `get_project_map` | Returns the pillar map, top-gravity files, and wild-discovery candidates. |\n| `set_project_brief` | Stores a 3–5 sentence project summary. Write this before any decision cards. |\n| `get_file_context` | Returns full source + import graph + hot spans for a specific file. |\n| `write_decision_card` | Persists a decision card (thesis, category, evidence, optional Mermaid diagram). |\n| `get_strategic_overview` | Returns dossier state without evidence snippets — useful for quick status checks. |\n| `inspect_pillar` | Returns all decision cards for a given architectural pillar. |\n| `get_wild_discoveries` | Returns the highest-complexity files that don't fit standard patterns. |\n| `mark_stale` | Marks a file's decision card as stale after you edit it. |\n\n---\n\n## How It Works\n\nvibesplain runs a deterministic static analysis pipeline — no model calls, no network:\n\n```\nYour project\n │\n ▼\nTree-Sitter AST parsing\n │\n ├── Gravity score (0–100)\n │ PageRank centrality × fan-in × cyclomatic complexity\n │ × public surface × nesting depth\n │\n ├── Heat score (0–100)\n │ Smell density: swallowed catches, deep nesting,\n │ long functions, god files, magic numbers\n │\n └── Pillar detection\n Auth / Database / Payments / Queue /\n Storage / Config / Email / Realtime / Logic\n │\n ▼\n .vibesplain/\n ├── dossier.json ← agent writes decision cards here\n ├── analysis.json ← raw scored file store\n ├── graph.json ← import graph\n └── ui/index.html ← self-contained dossier viewer\n```\n\n**Top 12 by gravity** = Start Here (the load-bearing hubs). \n**Top 12 by heat** = Wild Discoveries (the most complex / smelly files).\n\nThe UI is a single self-contained HTML file. Open it with `file://` — no server needed.\n\n---\n\n## Dossier UI\n\nAfter your agent writes decision cards, open the generated file:\n\n```\nfile:///path/to/your/project/.vibesplain/ui/index.html\n```\n\nFeatures:\n- Pillar tabs to navigate architectural areas\n- Decision cards with fresh/stale status\n- Mermaid diagrams rendered inline\n- Syntax-highlighted evidence snippets\n- Works fully offline from `file://`\n\n---\n\n## Architecture\n\n```\npackages/\n├── brain/ # @vibesplain/brain — pure static analysis, no I/O side effects\n│ └── src/\n│ ├── pipeline/ # 13-stage analysis pipeline\n│ │ └── adapters/ # Optional domain-adapter extension point (none bundled)\n│ ├── scanner.ts # Tree-Sitter AST + gravity/heat scoring\n│ ├── dossier.ts # Atomic dossier persistence + UI injection\n│ ├── analysis.ts # Scored file store + validation report\n│ └── graph.ts # Import graph read/write\n│\n├── cli/ # vibesplain — MCP server + CLI (the published npm package)\n│ └── src/\n│ ├── index.ts # CLI entrypoint\n│ ├── commands/\n│ │ ├── install.ts # Patches agent MCP configs\n│ │ └── serve.ts # Starts the MCP server\n│ ├── export/ # Artifact writing (HTML, Markdown, JSON)\n│ └── mcp/\n│ ├── server.ts # MCP tool registration\n│ └── tools/ # One file per tool\n│\n└── ui/ # @vibesplain/ui — React dossier viewer (embedded into cli at build time)\n```\n\n**Build order:** `brain` → `cli` → `ui` → `bundle-ui` (copies `ui/dist/` into `cli/dist/ui/`). \nOnly the `cli` package is published to npm.\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/abp2204/vibesplain.git\ncd vibesplain\nnpm install\nnpm run build # full build\nnpm run dev:ui # Vite dev server for the UI\nnpm run test:regression\n```\n\nTest locally after build:\n\n```bash\nnode packages/cli/dist/index.js install\nnode packages/cli/dist/index.js serve\n```\n\nPublish:\n\n```bash\nnpm run release\n```\n\n---\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}