🗺️ Vibe Map: Codebase Cartographer for Vibe Coders

Deeply analyzes any fast-growing codebase, parses multi-language ASTs, and creates layered visual architecture maps, user journeys, function directories, and blast-radius impact analysis.

Quickstart • Platforms • Visualizer • Commands • Comparison with Graphify

💡 The Problem & The Solution

When building apps with AI ("vibe coding" with Antigravity, Claude Code, Cursor, or Windsurf), codebases grow at lightning speed. Within hours, you can have 50+ React components, API routes, database schemas, and helper utilities.

Soon, builders face common challenges:

❓ "How does my app actually work under the hood?"
🔄 "When a user clicks a button, where does that data travel across the stack?"
📄 "What does each file and function do in simple plain English?"
💥 "If I ask the AI to modify file X, what other components might break?"

Vibe Map is a zero-dependency cartographer that instantly builds a crystal-clear mental model of your application, organizes code into intuitive architectural layers, and equips AI agents with shared structural memory.

✍️ Why I Built This (Author's Note)

"I originally created Vibe Map to solve a recurring challenge in my own AI-assisted projects. As my codebases grew rapidly with dozens of generated components, backend routes, and database models, I kept losing track of how everything connected under the hood. I needed an instant, zero-friction tool that could give me (and my AI agents) a clear architectural map, trace user flows, and calculate blast radius before making breaking edits. I built this tool for my own workflow and open-sourced it so other vibe-coders can build with total clarity."

Note

Just an experiment, which works for me so check before using 👍

🏗️ How It Works: The Tri-Artifact Standard

When vibe-map runs, it isolates all outputs into a single clean directory vibe-map-out/ (easily gitignored):

your-project/
└── vibe-map-out/
    ├── VIBE_MAP.md          # 📄 For Humans: Markdown guide with Mermaid topology & function catalog
    ├── codebase_map.json    # 📊 For AI Agents: Strictly typed graph for instant querying (<5ms)
    └── vibe_map.html        # 🌐 Visual Canvas: Zero-dependency dark-mode interactive explorer

graph LR
    Codebase[Raw Codebase] --> Parser[Multi-Language AST Parser]
    Parser --> Layers[Semantic Layer Classifier]
    Layers --> MD[VIBE_MAP.md<br/>Plain-English Guide]
    Layers --> JSON[codebase_map.json<br/>Multi-Agent Memory]
    Layers --> HTML[vibe_map.html<br/>Interactive Canvas]

⚡ Universal 1-Line Installation

Install vibe-map globally on your machine with a single command. It will auto-detect your environment and register the skill across all your workspaces:

🐧 Linux & 🍏 macOS (Terminal)

curl -fsSL https://raw.githubusercontent.com/muchandresh/Vibe-Map/master/install.sh | bash

🪟 Windows (PowerShell)

irm https://raw.githubusercontent.com/muchandresh/Vibe-Map/master/install.ps1 | iex

🐍 Python / Pip (Cross-Platform)

pip install git+https://github.com/muchandresh/Vibe-Map.git
vibe-map install --global

🐙 Local Git Clone

git clone https://github.com/muchandresh/Vibe-Map.git
cd Vibe-Map
./install.sh     # or: python3 install.py

🌐 Cross-Platform Installation Guide

vibe-map works natively across all major AI coding platforms:

1. 🪐 Google Antigravity (CLI & Desktop App)

Antigravity automatically discovers skills in global or workspace directories.

Global Installation (All Workspaces): Run vibe-map install --global or copy this repository to ~/.gemini/config/skills/vibe-map.
Project-Specific Installation: Drop this folder into .agents/skills/vibe-map within your project repository.

Trigger in Chat:

> /vibe-map
> "Map this codebase and explain the architecture"
> "What will break if I modify src/auth.py?"

2. 🤖 Claude Code

Add vibe-map to your project's CLAUDE.md to give Claude instant codebase mapping commands:

# In your CLAUDE.md:
## Architecture & Codebase Map
- Run `vibe-map` before starting major refactors or multi-file features.
- Inspect `vibe-map-out/VIBE_MAP.md` for architectural topology and layer breakdown.
- Run `vibe-map impact "<file>"` to check blast radius before making breaking changes.

3. ⚡ Cursor

Add vibe-map to your .cursorrules or .cursor/rules/vibe-map.md:

# Vibe Map Rule
- To understand project architecture, read `vibe-map-out/codebase_map.json`.
- Before editing shared utilities, run terminal command `vibe-map impact <file>` to verify dependent files.

4. 🌊 Windsurf (Cascade)

Add a workflow step to .windsurfrules:

- Whenever the user asks "How does this app work?" or "Map this project", run `vibe-map` and present the output from `vibe-map-out/VIBE_MAP.md`.

5. 💻 VS Code / Cline / Roo Code / Standalone Terminal

Simply run the CLI directly in any integrated terminal:

vibe-map

Double-click vibe-map-out/vibe_map.html to view the interactive visual map in your browser or VS Code simple browser preview!

🌟 Key Features & Capabilities

1. 🚀 Zero-Dependency Multi-Language AST Parsing

No compiler toolchains, C extensions, or heavy pip libraries required. Out-of-the-box support for:

Languages: Python, TypeScript, JavaScript, React JSX/TSX, Vue, Svelte, Go, Rust, Java, PHP, Ruby.
Database & Schemas: Prisma (schema.prisma), SQL migrations (.sql).
Configs & Infra: package.json, pyproject.toml, Dockerfile, YAML, TOML, Markdown.

2. 🏗️ Semantic Layer Categorization

Instead of confusing statistical graphs, files are organized into intuitive software layers:

Layer	Target File Types
Frontend / UI	Pages, components, views, layouts, hooks, styles (`.tsx`, `.jsx`, `.vue`, `.svelte`, `.css`)
Backend / API	Route handlers, controllers, endpoints, middleware, FastAPI, Express (`/api/`, `routes/`, `server.ts`)
Database / Models	Database schemas, ORM models, Prisma models, SQL tables (`models/`, `schema.prisma`, `.sql`)
Services / Logic	Business services, helpers, utilities, auth modules, background tasks (`services/`, `lib/`, `utils/`)
Config / Infra	Environment configs, package dependencies, Dockerfiles, build tools (`package.json`, `Dockerfile`)
Documentation	Readmes, architectural blueprints, guides (`.md`)

3. 💥 Blast-Radius Impact Analysis

Before asking an AI agent to refactor a function or delete a file, check what will break:

vibe-map impact "src/services/auth.ts"

💥 Blast Radius Analysis for `src/services/auth.ts`:
   Total Affected Files: 4

🔴 Direct Dependents (Break immediately if interfaces change):
   - `src/routes/login.ts`
   - `src/routes/register.ts`

🟡 Indirect Dependents (Downstream components):
   - `src/components/LoginForm.tsx`
   - `src/components/RegisterForm.tsx`

4. 🔄 Flow Tracer

Trace execution paths from UI components down to backend database tables:

vibe-map trace "LoginForm.tsx" "users_table"

🚀 Execution Flow Paths (1 found):
Path 1:
  ➔ `src/components/LoginForm.tsx`
  ➔ `src/api/authClient.ts`
  ➔ `backend/routes/auth.py`
  ➔ `backend/services/user_service.py`
  ➔ `backend/models/user.py (users_table)`

5. 🔍 Plain-English Feature Search

Search your codebase by feature concept instead of hunting through folders:

vibe-map explain "stripe"

🔍 Found 2 matching component(s) for 'stripe':

📄 `src/services/payment.ts` [Services / Logic]
   *Purpose:* Handles Stripe checkout sessions and webhook verification
   *Functions:*
     - `createCheckoutSession(userId, planId)`: Creates Stripe session URL
     - `handleWebhookEvent(event)`: Fulfills subscription on successful charge

🎓 Beginner-Friendly ELI5 Mode (`--deep`)

For non-technical founders, students, and new vibe-coders, vibe-map includes a dedicated Beginner Mode:

vibe-map --deep
# or in Antigravity chat: /vibe-map --deep

🎭 Real-World Analogies: Translates complex code into everyday metaphors ("The Cashier", "The Security Guard", "The Master Filing Cabinet").
💡 No-Jargon Summaries: Explains what each file and function does in simple everyday English.
📥 Input / Output Badges: Clear 📥 Takes in and 📤 Gives back descriptions for every function.
🔄 User Journey Maps: Shows where each component fits in the overall user experience.

📊 Token Usage: Standard vs. Deep Beginner Mode

Mode	Command	Token Cost	Speed	What It Does
Standard AST Scan	`vibe-map`	0 Tokens (100% Free)	Instant (<100ms)	Parses local AST files and builds structural dependency graphs entirely in Python. Zero LLM API calls.
Deep Beginner (ELI5) Mode	`vibe-map --deep`	Low to Moderate Tokens (One-time run)	2-5s	Powered directly by your active AI assistant (Antigravity, Claude, Cursor) in chat to generate deep analogies, no-jargon ELI5 summaries, and input/output cards. Zero external API keys needed.

Tip

Token Conservation Tip: You only need to run --deep once per major project milestone or when onboarding non-technical teammates. Subsequent refactors, blast-radius queries (vibe-map impact), and path traces run instantly with 0 tokens from the saved graph!

🌐 Interactive Visual Canvas & Dual-Mode Drawer

Opening vibe-map-out/vibe_map.html gives you a dark-mode interactive visual explorer with:

🎯 Physics Force-Directed Graph: Drag nodes, zoom, and pan across the architectural map.
🎓 Dual-Mode Inspection Drawer:
- Beginner (ELI5) Tab: Displays real-world analogies, simplified explanations, and input/output cards on every node click.
- Technical AST Tab: Displays raw code signatures, argument lists, in/out degrees, and file paths.
🎨 Color-Coded Layers: Color highlights for Frontend, Backend, Database, Services, and Infra.
🔍 Instant Search Bar: Filter by file name, function signature, analogy, or layer.
🪶 Zero Server Required: 100% self-contained HTML/JS. Double-click and open anywhere.

💡 Inspiration & Relationship with Graphify

vibe-map was inspired by the incredible vision of Graphify — the pioneering open-source tool that showed how transforming codebases into structured knowledge graphs can empower AI agents.

❓ "Are we using Graphify under the hood?"

No. vibe-map is 100% standalone and does NOT use or require Graphify as a dependency.

Here is why they are built differently:

Graphify is a heavyweight, research-grade knowledge graph and GraphRAG engine. It uses NetworkX, Louvain community clustering, Whisper audio transcription, Cypher/Neo4j, and Gemini semantic extraction for massive multimodal corpora (code + PDF research papers + videos).
Vibe-Map was engineered specifically for vibe coders and fast-moving AI developers who need an instant, zero-friction tool. It requires zero external pip dependencies, parses multi-language ASTs natively in milliseconds, organizes code into layered software stacks (UI ➔ API ➔ DB), and calculates blast-radius impact analysis before AI agents make edits.

🆚 Vibe-Map vs. Graphify: Direct Comparison

Dimension	🗺️ `vibe-map` (This Project)	🕸️ `Graphify`
Origin & Inspiration	Inspired by Graphify, tailored for Vibe Coding	Pioneer in Codebase Knowledge Graphs & GraphRAG
Target Audience	Vibe Coders, Solo Founders, AI App Builders	Researchers, Data Scientists, Enterprise Architects
Primary Mental Model	Software Architecture (UI ➔ API ➔ DB)	Graph Theory (God nodes, Louvain clusters, bridges)
External Dependencies	Zero (Pure Python 3 standard library)	`networkx`, `whisper`, `pip` packages
Speed & Setup	Instant (< 100ms), 1-line install, 0 setup	Requires pip install and optional Gemini/Whisper setup
Multi-Language Support	Python, JS, TS, React, Vue, Svelte, Go, Rust, SQL, Prisma	Code AST (Python/JS) + Multimodal Docs/Audio/Video
Visualizer	Standalone zero-server interactive HTML + Mermaid	D3 HTML visualizer, Obsidian vault, Neo4j, FalkorDB
Change Management	Blast-Radius Impact Calculator (`vibe-map impact`)	Graph traversal, shortest path BFS/DFS, community queries
Multi-Agent Memory	Ultra-fast `codebase_map.json` (< 5ms load)	GraphRAG-ready JSON + Neo4j Cypher queries

🤝 Can You Use Both Together? (Hybrid Mode)
Yes! If you are working on a complex project with research papers, PDF documentation, and code, you can use Graphify for multimodal GraphRAG and use vibe-map for day-to-day coding, visual architecture maps, and blast-radius checks before making code edits.

🎮 CLI & Slash Command Reference

Command	In Antigravity Chat	In Terminal	Description
Scan Codebase	`/vibe-map`	`vibe-map`	Full AST scan & artifact generation
Beginner / ELI5 Mode	`/vibe-map --deep`	`vibe-map --deep`	AI/ELI5 beginner enrichment with analogies & IO cards
Scan Subdirectory	`/vibe-map src/`	`vibe-map src/`	Scan a specific folder or package
Impact Analysis	`/vibe-map impact <file>`	`vibe-map impact <file>`	Calculate blast radius of file modifications
Trace Flow	`/vibe-map trace <a> <b>`	`vibe-map trace <a> <b>`	Trace data flow between two components
Explain Feature	`/vibe-map explain <term>`	`vibe-map explain <term>`	Plain-English summary of matching files & functions
Install Skill	—	`vibe-map install --global`	Auto-install skill into Antigravity global config

🤝 Multi-Agent Shared Context

When using parallel AI agents or subagents (e.g., Antigravity subagents, Claude Code parallel agents, Cursor Composer):

Agents do not need to sequentially read every file to understand the workspace.

They can load vibe-map-out/codebase_map.json in < 5ms:

import json
from pathlib import Path

map_data = json.loads(Path("vibe-map-out/codebase_map.json").read_text())
# Instant access to all entrypoints, hubs, routes, and function signatures

Saves thousands of tokens per prompt and prevents context-window degradation!

🧪 Testing

Run the included test suite to verify AST parsers, edge cases, and query engine:

python3 tests/run_tests.py

📄 License

MIT License. Free for open-source and commercial use. Contributions welcome!

Note

Just an experiment, which works for me so check before using 👍

Name		Name	Last commit message	Last commit date
references		references
templates		templates
tests		tests
vibe_map		vibe_map
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SKILL.md		SKILL.md
install.ps1		install.ps1
install.py		install.py
install.sh		install.sh
pyproject.toml		pyproject.toml
setup.py		setup.py
tags.sh		tags.sh

Navigation Menu

Repository files navigation

🗺️ Vibe Map: Codebase Cartographer for Vibe Coders

💡 The Problem & The Solution

✍️ Why I Built This (Author's Note)

🏗️ How It Works: The Tri-Artifact Standard

⚡ Universal 1-Line Installation

🐧 Linux & 🍏 macOS (Terminal)

🪟 Windows (PowerShell)

🐍 Python / Pip (Cross-Platform)

🐙 Local Git Clone

🌐 Cross-Platform Installation Guide

1. 🪐 Google Antigravity (CLI & Desktop App)

2. 🤖 Claude Code

3. ⚡ Cursor

4. 🌊 Windsurf (Cascade)

5. 💻 VS Code / Cline / Roo Code / Standalone Terminal

🌟 Key Features & Capabilities

1. 🚀 Zero-Dependency Multi-Language AST Parsing

2. 🏗️ Semantic Layer Categorization

3. 💥 Blast-Radius Impact Analysis

4. 🔄 Flow Tracer

5. 🔍 Plain-English Feature Search

🎓 Beginner-Friendly ELI5 Mode (`--deep`)

📊 Token Usage: Standard vs. Deep Beginner Mode

🌐 Interactive Visual Canvas & Dual-Mode Drawer

💡 Inspiration & Relationship with Graphify

❓ "Are we using Graphify under the hood?"

🆚 Vibe-Map vs. Graphify: Direct Comparison

🎮 CLI & Slash Command Reference

🤝 Multi-Agent Shared Context

🧪 Testing

📄 License

Note

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🗺️ Vibe Map: Codebase Cartographer for Vibe Coders

💡 The Problem & The Solution

✍️ Why I Built This (Author's Note)

🏗️ How It Works: The Tri-Artifact Standard

⚡ Universal 1-Line Installation

🐧 Linux & 🍏 macOS (Terminal)

🪟 Windows (PowerShell)

🐍 Python / Pip (Cross-Platform)

🐙 Local Git Clone

🌐 Cross-Platform Installation Guide

1. 🪐 Google Antigravity (CLI & Desktop App)

2. 🤖 Claude Code

3. ⚡ Cursor

4. 🌊 Windsurf (Cascade)

5. 💻 VS Code / Cline / Roo Code / Standalone Terminal

🌟 Key Features & Capabilities

1. 🚀 Zero-Dependency Multi-Language AST Parsing

2. 🏗️ Semantic Layer Categorization

3. 💥 Blast-Radius Impact Analysis

4. 🔄 Flow Tracer

5. 🔍 Plain-English Feature Search

🎓 Beginner-Friendly ELI5 Mode (--deep)

📊 Token Usage: Standard vs. Deep Beginner Mode

🌐 Interactive Visual Canvas & Dual-Mode Drawer

💡 Inspiration & Relationship with Graphify

❓ "Are we using Graphify under the hood?"

🆚 Vibe-Map vs. Graphify: Direct Comparison

🎮 CLI & Slash Command Reference

🤝 Multi-Agent Shared Context

🧪 Testing

📄 License

Note

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

🎓 Beginner-Friendly ELI5 Mode (`--deep`)