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

/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:

# 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

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:

   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:

vibe-map impact "<file_name>"

Outputs direct dependents (which will break immediately if APIs change) and indirect downstream dependents.

2. Tracing Component Data Flow

vibe-map trace "<source_component>" "<target_database_or_service>"

Traces call chains from UI inputs to backend databases.

3. Feature & Function Search

vibe-map explain "<keyword>"

Finds all relevant files, route handlers, and functions matching the query with plain-English summaries.

4. Deep Beginner (ELI5) Enrichment

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)

{
  "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. vibe-map is 100% standalone and does NOT require Graphify as a dependency.

💡 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.