# Vibe Map

> Codebase cartographer and architecture explainer tailored for vibe coders and builders. Deeply scans directories, builds visual component maps, user journeys, function-by-function breakdowns, and impact blast-radius analysis.

- Skill: `muchandresh/vibe-map` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add muchandresh/vibe-map`
- Raw SKILL.md: https://api.skillmd.com/api/skills/muchandresh/vibe-map/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: muchandresh (https://skillmd.com/u/muchandresh)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/muchandresh/vibe-map

---


# /vibe-map

Turn any messy, fast-growing codebase into a crystal-clear, plain-English architectural blueprint with interactive visuals, function directories, and blast-radius impact analysis.

---

## 🎯 What Vibe-Map is For

When "vibe coding" with AI, applications grow fast—often accumulating dozens of React components, API endpoints, utilities, and database schemas. Builders often ask:
- *"How does my app actually work under the hood?"*
- *"When a user clicks a button, where does that data go?"*
- *"What does each file and function do in simple English?"*
- *"If I tell the AI to edit file X, what else might break?"*

`vibe-map` provides a fast structural overview:
1. **Automated Parsing and Heuristics**: Python AST parsing plus lightweight structural support for JavaScript, TypeScript, React JSX/TSX, Vue, Svelte, Go, Rust, SQL, Prisma, and configs.
2. **Plain-English Mental Model**: Translates raw code into layered user journeys (Frontend ➔ API ➔ Logic ➔ Database).
3. **Dual Storage Layer**: Structured machine JSON (`codebase_map.json`) for AI agents + human markdown (`VIBE_MAP.md`) + zero-dependency interactive canvas (`vibe_map.html`).
4. **Blast-Radius Impact Analyzer**: Computes upstream and downstream ripple effects before code changes.

---

## ⚡ Usage & Slash Commands

```bash
/vibe-map                                      # Full scan & map generation on current workspace
/vibe-map <path>                               # Run map on specific subfolder or project
/vibe-map update [path]                        # Refresh a map after source changes
/vibe-map --update                             # Alias for refresh
/vibe-map explain "<feature_or_file>"          # Plain-English explanation of a feature or file
/vibe-map trace "<start_file>" "<target_file>" # Trace known dependency paths between two components
/vibe-map impact "<file_path>"                 # Predict blast radius / dependent files if edited
/vibe-map --json-only                          # Generate only machine-readable JSON for agents
```

### Natural Language Triggers
- *"Map this app"* / *"Generate a vibe map"*
- *"Explain how this codebase connects"*
- *"What is the architecture of this project?"*
- *"Show me all functions and what they do"*
- *"What will break if I change this file?"*

---

## 🚀 Execution Pipeline

Follow these steps in order when invoked.

### Step 0: Fast-Path for Existing Maps
Before running a fresh scan, check if `vibe-map-out/codebase_map.json` or `vibe-map-out/VIBE_MAP.md` already exists:
- If it exists **AND** the user is asking a targeted question (e.g., *"How does auth work?"*, *"Trace X to Y"*, *"What does function Z do?"*):
  - Skip full scanning and run `python3 -m vibe_map.cli explain/trace/impact` or read `codebase_map.json` directly.
  - Return the answer immediately to save time and tokens.

### Step 1: Run Multi-Language Cartographer
Execute the built-in parser against the target directory:

```bash
# Standard structural scan (0 tokens)
vibe-map "<TARGET_DIR>"

# Or Deep Beginner (ELI5) Mode with full semantic enrichment:
vibe-map "<TARGET_DIR>" --deep
```

*This parses Python ASTs, applies lightweight structural heuristics to supported formats, resolves known local/package imports, catalogs functions/classes, detects entrypoints and hubs, and produces three primary outputs inside `vibe-map-out/`. Add `--deep` to include local heuristic analogies and ELI5 descriptions.*

### Step 2: Outputs Generated

| Artifact | Location | Purpose |
| :--- | :--- | :--- |
| **`VIBE_MAP.md`** | `vibe-map-out/VIBE_MAP.md` | Human-readable architectural guide, Mermaid diagrams, Beginner Mental Model, and function directory. |
| **`codebase_map.json`** | `vibe-map-out/codebase_map.json` | Machine-readable node-edge graph for parallel/subsequent AI agent querying; `--deep` adds ELI5 fields. |
| **`vibe_map.html`** | `vibe-map-out/vibe_map.html` | Standalone interactive visual canvas with tabbed Beginner (ELI5) and Technical drawers. |

### Refreshing an Existing Map

After the project changes, use `vibe-map update` (or `vibe-map --update`). The command performs a complete rescan so additions, edits, renames, and deletions are correct, then writes an update summary to both the terminal and graph metadata. For a custom output location, use `vibe-map update --map <path/to/codebase_map.json>`.

### Step 3: Agent AI Semantic Enrichment (When `--deep` or beginner mode is requested)
When `/vibe-map --deep` is run inside an AI agent session (like Antigravity or Claude Code):
1. Read `vibe-map-out/codebase_map.json` to inspect the generated nodes.
2. As the host AI agent, **use your model's reasoning** to generate custom, non-generic beginner explanations for the project's key files and functions:
   - `node["analogy"]`: A fun, relatable metaphor with emoji (e.g. `🛡️ The Security Guard`, `💳 The Cash Register`, `🗄️ The Filing Cabinet`).
   - `node["eli5"]`: 2 simple sentences explaining what this file does without jargon.
   - `node["user_journey_step"]`: Where this file is active during app usage.
   - `fn["what_it_does_simple"]`: What each function actually does in plain English.
   - `fn["takes_in"]` & `fn["gives_out"]`: Simple inputs and return values.
3. Save the enriched data back to `vibe-map-out/codebase_map.json` and run:
   ```bash
   python3 -m vibe_map.enricher re-render vibe-map-out
   ```
   *This automatically updates both `vibe-map-out/VIBE_MAP.md` and `vibe-map-out/vibe_map.html` with your custom AI explanations!*

### Step 4: Present Summary in Chat
Present a clear, beginner-friendly summary to the user:
- 📖 **The Big Picture**: 2-3 sentences explaining what problem this app solves.
- 🔄 **Core User Journey**: Step-by-step walkthrough of what happens when a user uses the app.
- 🎭 **Component Cast & Roles**: Table listing each major file with its real-world analogy and plain-English purpose.
- 📊 **Quick Stats & Hubs**: Files analyzed, functions cataloged, and top entrypoint files.
- 🎨 **Visuals**: Embedded Mermaid topology diagram.
- 🔗 **Clickable Links**: Links to `[VIBE_MAP.md](file:///path/to/vibe-map-out/VIBE_MAP.md)` and `[vibe_map.html](file:///path/to/vibe-map-out/vibe_map.html)`.

---

## 🔍 Subcommands & Querying

### 1. Blast-Radius Impact Analysis
When the user wants to refactor or modify a file:
```bash
vibe-map impact "<file_name>"
```
*Outputs direct dependents (which will break immediately if APIs change) and indirect downstream dependents.*

### 2. Tracing Component Data Flow
```bash
vibe-map trace "<source_component>" "<target_database_or_service>"
```
*Traces call chains from UI inputs to backend databases.*

### 3. Feature & Function Search
```bash
vibe-map explain "<keyword>"
```
*Finds all relevant files, route handlers, and functions matching the query with plain-English summaries.*

### 4. Deep Beginner (ELI5) Enrichment
```bash
vibe-map --deep
```
*Generates rich beginner analogies, input/output breakdowns, and step-by-step user journey maps.*

---

## 🛠️ Storage & Format Architecture

### Why This Storage Design?
1. **Zero External Dependencies**: Runs instantly on standard Python 3 without requiring heavy C extensions, compilation, or third-party graph packages.
2. **Multi-Agent Shared Memory**: Any subagent or external tool can load `codebase_map.json` in `< 5ms` to understand workspace context without token-heavy directory scraping.
3. **Immediate Visual Preview**: `vibe_map.html` is 100% self-contained—users can open it directly in their desktop browser or IDE webview without running local web servers.

### Graph Schema (`codebase_map.json`)
```json
{
  "root": "/path/to/project",
  "stats": { "total_files": 25, "total_functions": 120, "layers": {...} },
  "nodes": [
    {
      "id": "src/components/Checkout.tsx",
      "name": "Checkout.tsx",
      "path": "src/components/Checkout.tsx",
      "type": "file",
      "lang": "react-tsx",
      "layer": "Frontend / UI",
      "summary": "Renders user payment form and submits transaction payload",
      "functions": [
        { "name": "handlePayment", "args": ["token", "amount"], "summary": "Submits payment token to /api/charge" }
      ],
      "in_degree": 2,
      "out_degree": 4,
      "is_entrypoint": false,
      "is_hub": false
    }
  ],
  "edges": [
    { "source": "src/components/Checkout.tsx", "target": "src/api/charge.ts", "type": "imports" }
  ]
}
```

---

## 🤝 Relationship with Graphify (Vibe-Map vs Graphify)

`vibe-map` was inspired by the vision of [**Graphify**](https://github.com/Graphify-Labs/graphify). `vibe-map` is **100% standalone and does NOT require Graphify as a dependency**.

| Feature | `vibe-map` (This Skill) | [`graphify`](https://github.com/Graphify-Labs/graphify) |
| :--- | :--- | :--- |
| **Target Audience** | **Vibe Coders & Product Builders** | **Researchers, Architects & Data Scientists** |
| **Core Output** | Plain-English user flows, function guides, visual HTML canvas | GraphRAG JSON, Louvain communities, Neo4j/Cypher |
| **Dependencies** | **Zero** (Pure Python standard library) | `networkx`, `whisper`, `pip` packages |
| **Language Support** | Python, JS, TS, React, Vue, Svelte, Go, Rust, SQL, Configs | Code + PDF papers, Markdown, Audio/Video transcripts |
| **Mental Model** | Architectural Layers (UI ➔ API ➔ DB) | Graph Theory (God nodes, Surprising connections) |
| **Hybrid Mode** | Can run alongside Graphify or export nodes to Graphify format | Supported via `references/comparison_with_graphify.md` |

---

## 💡 Best Practices for Antigravity Pairing
- **Before major features**: Run `/vibe-map impact <file>` to verify what other components will be touched.
- **When resuming an old project**: Type `/vibe-map` to instantly rebuild your mental model of the codebase.
- **For desktop app users**: Open `.agents/vibe_map/vibe_map.html` in your browser for a live interactive visual map.