Codebase sync & Code Map

A structural map of your existing codebase, submitted by your IDE agent and used to ground VibeMap's generation in the code you already have. · Optional

Use this when you're bringing VibeMap to an existing project rather than starting from a blank prompt. Your AI coding agent scans your repo, submits a code map, and VibeMap draws it on the Codebase tab and links your features to the real files that implement them. If you're building something brand-new, you can skip this whole section.

How the flow works

The code map travels over the same MCP connection you set up for handoff — you don't connect anything new. See 11.2 Connect your IDE first if your agent isn't wired up yet.

1. Open your project and go to the Codebase tab. If no map exists yet, you'll see a "No code map yet" panel with a ready-made prompt.
2. Copy that prompt and paste it into your IDE agent (Claude Code, Cursor, or Windsurf). It asks the agent to explore your repo and call the vibemap_submit_code_map tool. Not connected yet? Open Use in IDE in the sidebar for the setup kit.
3. Your agent walks the codebase and submits one node per page/route, API endpoint, data model, service, and significant module — plus the edges between them (imports, routes, reads, writes) and the current commit SHA as an anchor.
4. The map lands as a draft. The Codebase tab renders it as an interactive diagram: nodes are colour-coded by layer (ui, api, data, services, shared) and you can pan, zoom, and search.

Reviewing and curating the map

The header bar shows a status chip (Draft — confirm to enable generation), the unit and relation counts, any hidden count, and the short commit SHA the map was taken at.

• Search — filter units by name or path; non-matching nodes dim.
• Inspect a node — click any node to open a detail panel with its kind, layer, file path, and summary. If a feature has been linked to it, you'll see an Implements chip listing that feature (see Feature provenance below).
• Hide noise — use Hide from map on a node to drop generated boilerplate, vendored code, or anything you don't want grounding your specs. Hidden units collect in a Hidden row you can restore from with one click. Curating the map drops it back to draft.

💡 Tip: The map caps at 500 nodes. If your agent hits the ceiling it aggregates small files into their parent module, so you get architecture rather than a file listing.

Confirming and generating

When the map reflects your app, click Confirm map. Confirming unlocks Generate specs from this map — VibeMap runs a grounded generation chain in order:

Features → User stories → Acceptance criteria

A progress meter shows each step completing. Because generation reads your actual code map, the features it proposes describe what your app really does — not a guess from a one-line prompt. When the chain finishes, you're pointed to the Features page to review.

⚠️ Watch out: Viewing and curating the code map is available on every plan, but generating specs from it is a Pro-and-up feature. Below Pro you'll see a Generate specs (Pro) button that links to billing.

Feature provenance

After generation, VibeMap runs a deterministic pass that matches your features against the map's nodes and records the links. That's what powers the Implements chips in the node detail panel and the file links on features — so you can always trace a feature back to the code that satisfies it, and vice versa.

⚡ Power-user hints

• The whole flow is agent-driven: you can skip the paste-a-prompt step entirely and just tell your connected agent "build a code map of this repo and submit it to my VibeMap project" — it already has the vibemap_submit_code_map tool.
• Re-submitting a map replaces the previous one (matched on your project), so re-running the scan after a big refactor is safe and idempotent.
• The commit SHA the agent stamps on the map is what later powers drift detection — keep it accurate by letting the agent read git rev-parse HEAD rather than hand-editing.

↔ The traditional way

Onboarding a new engineer to an unfamiliar codebase means hours of reading files, sketching the architecture on a whiteboard, and reverse-engineering what each feature touches — knowledge that lives in one person's head and goes stale the moment someone merges. The code map makes that structural picture a shared, clickable artifact your whole team (and your AI agent) can reason over, and ties every feature to the files that implement it automatically.

What's next

• Keep spec and code in step → 12.2 Drift detection.
• Connect your IDE first → 11.2 Connect your IDE.
• Review the generated features → 5.1 Generating features.