Codemap

Turn any repository into a map you can explore. Point Codemap at a codebase and it produces a single self-contained HTML file — a pan/zoom/searchable atlas where every file is a star, every import is a line between them, size is lines of code, and (if it's a git repo) the busiest, most-churned files rise to the surface.

No dependencies. No install. No account. One command in, one HTML file out — open it, or send it to a teammate who's never cloned the repo.

▸ See the website · open the interactive map — a real Codemap of the bundled sample project. Drag to pan, scroll to zoom, click a file to trace its imports.

              ● src/index.js
             ╱
   src/app.js ●───────● src/ui/modal.js
        │  ╲          ╱
        │   ● src/store/state.js
        │        ╲
   src/util/dom.js ●───● src/util/events.js

Why

Every codebase has a shape, but you can only ever see one file at a time. New hires spend weeks building a mental map that already exists — it's just invisible. Codemap makes it visible in one command: what depends on what, where the gravity is, which files everything routes through, and which corners are dead weight. It's a README you don't have to write and can't let go stale.

Use it

# from anywhere, no install:
node codemap.js /path/to/repo -o map.html --open

# or map the current directory:
node codemap.js .

Flags: -o <file> output path (default codemap.html), --open open it when done.

That's it. The output is a normal HTML file — double-click it, host it, attach it to a PR.

What it does

• Builds the real import graph. Parses import / require / dynamic import() / export … from (JavaScript, TypeScript, JSX/TSX, Vue, Svelte), import / from … import (Python), and @import (CSS/SCSS), then resolves relative specifiers to actual files — with extension and index/__init__ resolution. External packages become a per-file "ext deps" count, not noise on the graph.
• Weighs every file. Node size scales with lines of code; hover to see language, LOC, link count, external deps, and — in a git repo — how many commits have touched it (churn), so the files that change constantly are easy to spot.
• Lays it out deterministically. A seeded force-directed layout runs in the CLI, so the same repo always produces the same map (clean diffs, no jitter between runs). The browser just renders it — fast, even for large graphs.
• Ships a real viewer. Canvas-rendered, 60fps pan/zoom, live file search, click-to-isolate a file and its neighbors, color by directory or language, a clickable legend to mute whole areas, a minimap, an animated intro, and keyboard shortcuts (/ search · f fit · h hotspot · esc clear). Light and dark. Works on a phone.
• Hotspot mode. Flip one toggle and files resize by git churn instead of lines of code, so the code that changes most — the real risk surface — floats to the top.
• Stays offline. The emitted HTML loads nothing from the network — the graph data is inlined. A test in this repo fails the build if the viewer ever gains a <script src>, external stylesheet, or fetch().

Supported languages

Graph edges: JavaScript, TypeScript, JSX/TSX, Vue, Svelte, Python, CSS/SCSS. Files in other common languages (Go, Rust, Ruby, Java, C/C++, C#, Swift, Kotlin, PHP, Shell, …) still appear as sized, colored, churn-weighted nodes; richer cross-file resolution for them is on the roadmap.

How the layout works

Codemap runs a Fruchterman–Reingold force simulation seeded with a fixed PRNG: files repel each other, imports pull connected files together, and a gentle gravity keeps the whole thing centered. Because the seed is fixed, layout is reproducible. For very large repos (>1500 files) it keeps the heaviest files — by size, churn, and connectivity — and prints exactly how many it omitted, so a big map never silently hides half the codebase.

Develop

No build step, no dependencies. Edit codemap.js and re-run. The test suite runs the actual CLI against sample-project/ and checks the resolved graph, layout determinism, and that the emitted HTML is fully self-contained:

node test.js      # or: npm test
npm run demo      # regenerate docs/index.html (the live demo)

Roadmap

• Cross-file resolution for Go / Rust / Ruby / Java
• "Hotspot" mode — size by churn instead of LOC — shipped
• Cluster/collapse by directory for very large repos
• Export the graph as JSON / DOT for other tools
• Diff two commits and animate what moved

License

MIT © 2026 Adeeb Bashir (zent7x)

---

Built by Adeeb Bashir (zentex) · zent7x.com