VibeCodeMap

Understand any app at a glance. VibeCodeMap turns code into an interactive 3D city, revealing architecture, dependencies, quality signals, side effects, and potential issues.

Comment

Inspiration

AI can generate thousands of lines of software faster than a human can understand the resulting system. The code may run, but architecture, interactions, side effects, quality signals, and uncertainty quickly disappear into folders and files.

I built VibeCodeMap to make that system visible again. The central idea is simple: turn a codebase into a navigable software city, while keeping every important claim connected to evidence and clearly separating measured facts from AI interpretation.

What it does

VibeCodeMap is an experimental evidence model and interactive 3D condition map for software repositories.

In the visualization:

  • products and systems become cities;
  • independently built applications, services, workers, and CLIs become areas;
  • features, layers, and subsystems become districts;
  • components, interfaces, resources, actors, and expected-but-missing parts become buildings;
  • calls, events, state access, external providers, and static imports become visually distinct typed roads; and
  • source-linked measurements appear as condition bands around buildings.

Users can orbit and search the map, filter relation families, select a building, inspect its mapped neighborhood, review inputs and outputs, see available quality evidence, and navigate back to the relevant source location.

Unknown evidence remains unknown rather than becoming a misleading zero. Security markers and quality signals are investigation leads, not automatic verdicts. VibeCodeMap is a research prototype, not a dependable code-audit product.

How it works

The end-to-end workflow has five stages:

  1. vibecodemap inspect inventories the repository once, detects stack candidates, and creates a bounded reading plan that excludes generated code, installed dependencies, caches, and other noise.
  2. vibecodemap analyze runs every implemented analyzer over that same reviewed scope. Current prototypes support Go and Python AST analysis plus conservative JavaScript/TypeScript lexical analysis.
  3. A checked-in Codex skill guides GPT-5.6 through the semantic investigation that deterministic analyzers cannot finish alone. It discovers deployables and subsystems, reviews source evidence, and authors editable structural and project DSL.
  4. vibecodemap quality maps supported deterministic measurements into source-linked quality DSL while preserving unavailable metrics as unknown.
  5. vibecodemap show validates the models, composes renderer-neutral view JSON, generates a standalone Three.js HTML map, and opens it in the browser.

The hosted demo dogfoods the complete idea: VibeCodeMap maps VibeCodeMap itself. Judges can explore that artifact directly in a browser without installing Go, Python, or any analyzer.

How I used Codex and GPT-5.6

Codex with GPT-5.6 in Sol Max mode was my primary engineering environment from initial concept through submission.

I provided the problem, the software-city metaphor, the visual grammar, and the product constraints. Codex and GPT-5.6 helped turn that direction into the Go CLI, DSL contracts and JSON Schemas, repository scoping, prototype language analyzers, quality-evidence bridge, validation pipeline, Three.js renderer, tests, documentation, hosted site, and the self-map used in this demo.

GPT-5.6 also has an active role in the VibeCodeMap development workflow. Through the repository-owned $analyze-with-vibecodemap skill, it investigates approved source, identifies system boundaries and relationships, tracks review coverage, and authors source-linked semantic DSL. AI architectural claims are marked with ai_inferred provenance, confidence, rationale, and source evidence.

This is deliberately a development-time agent workflow rather than a hidden runtime API dependency. The generated map and hosted viewer require no OpenAI credentials.

Challenges

The hardest challenge was not drawing a city. It was deciding what the city is allowed to claim.

Static imports are topology, not observed runtime communication. An async keyword does not prove queued delivery. Missing coverage data does not mean zero coverage. A suspicious pattern is not automatically a vulnerability. These distinctions had to survive every layer: analyzers, DSL schemas, validation, composition, legends, roads, condition bands, and documentation.

Another challenge was making a repository-scale map readable. File-per-building visualizations immediately become noise, so VibeCodeMap uses semantic hierarchy, editable clustering, affinity signals, aggregated roads, label modes, search, and progressive detail.

The final challenge was producing a no-install judging experience. The repository now contains a generated self-map and a hosted product page that embeds it directly, with a readable evidence fallback when WebGL or the current Three.js CDN is unavailable.

Accomplishments I am proud of

  • One Go CLI owns inspection, analyzer orchestration, evidence-to-quality conversion, validation, composition, HTML generation, and browser launch.
  • Structural, project, quality, and renderer contracts remain editable and schema-validated.
  • Important buildings and relations carry repository-relative source evidence.
  • Deterministic measurements and AI inference remain visibly separate.
  • The generic renderer can display multiple systems, districts, buildings, typed aggregate roads, condition bands, boundaries, security-review leads, and expected-but-missing components.
  • The project successfully maps and presents its own implementation as the public demo.

What I learned

AI-generated software needs more than another code browser. It needs a review surface that shows what is known, how it is known, and what still requires human judgment.

I also learned that provenance is a product feature, not metadata hidden in a backend. Confidence, source locations, missing evidence, and the difference between static and runtime claims must be visible in the interaction itself.

What's next

Next I would add compiler-grade JavaScript/TypeScript analysis, native semantic adapters for currently detection-only mobile stacks, import of coverage and SARIF results, optional runtime traces, stronger large-workspace layout, and collaborative correction workflows. The long-term goal is not automatic truth—it is a faster, clearer, evidence-backed conversation between developers, AI agents, and the software they are building.

Built With

Share this project:

Updates