CodeMap
A 3D, Tron-style map of a git repository. Files are towers, folders are districts, and the commit
history is a timeline you can scrub or play. Load any public GitHub repo in the browser, open a
folder from your own disk, or scan a local checkout.
Live: https://codemap-3d.netlify.app · Try a repo: https://codemap-3d.netlify.app/?gh=owner/name
What it shows
| View | Geometry |
|---|
City (1) | file = tower (height = lines, footprint = share of its folder), folder = district |
Graph (2) | the import network in free space |
Strata (3) | each tower is a stack of slabs, one per commit that touched it |
Lenses (L) colour the towers: change (what the selected commit touched, or the uncommitted
working tree), language, churn and age. The timeline steps through commits; its last
stop is the working tree. Click a tower for the code panel: source with a blame gutter, dirty
lines, per-commit diffs and symbols. A selected file draws arcs to what it imports and what imports
it.
Getting around
Press ? in the app for every key and mouse control.
- Camera presets (bottom right): TOP (
T) is an orthographic top-down map where dragging pans
like a map; ISO (I), FRONT and SIDE; FRAME (.) fits the selection; ORTHO (O) toggles
orthographic; RESET (Home) goes back to the whole repo. The axis gizmo swings the camera to
look along the axis you click.
- Folder tree (top left): the repo at the current commit, each folder with its count of added,
modified and deleted files. CHANGED hides untouched files.
- Focus: click a folder in the tree, click a folder label in the scene, or double-click a tower
to focus its folder. The rest of the city slides away and fades;
Backspace, Esc (with nothing selected) or the
breadcrumb goes back up; Esc at the top level opens the menu.
/ searches files, ← → step commits, Space plays the history, F free-flies (WASD).
Run it locally
Needs Node 20.19+ (or 22.12+), Python 3.10+ and git.
cd web
npm install
npm run dev # http://127.0.0.1:5179
Scan a local repo
npm run scan -- ../path/to/repo # relative to where you run it
The scanner (scan/scan.py, standard library only) writes web/local-maps/<repo>.json with each
file's text, symbols, imports and per-line blame, the working tree's dirty lines, and every commit
with its patches. Every scanned repo appears in the menu (Esc) and at ?repo=<name>; the menu
can rescan the current one.
Local scans contain the full source of the repo. web/local-maps/ is git-ignored and only
the dev server serves it. It never goes into a build. Don't copy a private scan into
web/public/.
Load from GitHub
Menu → Load from GitHub, or open ?gh=owner/name&n=50. The browser reads the tree, the last n
commits and their diffs from the GitHub API, and file contents from raw.githubusercontent.com.
Nothing is cloned and there is no backend in the loop. Without a token GitHub allows 60 API calls
an hour. A token (sign in, or paste one) raises that to 5,000 and reaches private repos.
Open pull requests
To see how a PR changes the map, use "Browse open PRs" in the same menu section (it lists the typed
repo, or the one on screen), or open ?gh=owner/name&pr=123. owner/name#123 and
github.com/owner/name/pull/123 URLs work in the input too. The city is the tree at the PR's head
and the timeline is the PR's own commits (up to 100), so the CHANGE lens and the commit slider
show exactly what the PR touches. Fork PRs load through the base repo.
Tokens are kept in the tab's sessionStorage and sent only to api.github.com. The live site's
Content-Security-Policy only lets the page talk to itself, the GitHub API and the raw-content
host.
Open a local folder
Menu → Open a local folder, or open ?local&n=50, then CHOOSE FOLDER. This works the same on the
live site and under npm run dev, with no scan step: the browser's folder picker hands the files
to the page and everything is read inside the tab. Nothing is uploaded, and the CSP would block
the page from sending the files anywhere but GitHub.
History comes from the folder's own .git: the last n commits on the current branch's
first-parent line (a merge shows everything it brought in), with their diffs, and the working
tree's dirty lines against HEAD. The file list follows the folder's .gitignore files and
.git/info/exclude, and skips nested repositories as git does. Your global ignore file
(~/.config/git/ignore) sits outside the folder, so it isn't applied. Compared with the scanner
there is no blame, renames are found only when the contents are identical, and a worktree or
submodule (where .git is a pointer file) opens without history. Chrome, Edge and Arc read the folder lazily. Firefox and Safari read every file in it up
front, node_modules included, so use Chrome for big repos.
Feedback
FEEDBACK (under KEYS, and in the menu) opens a prefilled new-issue page on GitHub in a new tab.
It has a "what happened / what I expected" section and a short context block: app version, view,
camera, lens and your browser. The repo name is added only for the bundled demos and for public
repos loaded from GitHub without a token; a local scan or picked folder is never named. Nothing is
sent by the app: you review the text and submit it from your own GitHub account. Without the app,
use New issue → Feedback on the repository. If the repository moves, change FEEDBACK_REPO in
web/src/feedback.js and the link in .github/ISSUE_TEMPLATE/config.yml.
Deploy your own (Netlify)
netlify.toml builds web/, serves web/dist, sets the security headers and deploys one function,
web/netlify/functions/github-token.mjs. The page works without sign-in (public repos, or a pasted
token). To add the Sign in with GitHub button:
- Create a GitHub App (preferred: read-only Contents and Metadata, the user picks which
repos) or a classic OAuth App. Set the callback URL to the site root, e.g.
https://<site>.netlify.app/.
- Set Netlify environment variables:
GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET (server-side
only), VITE_GITHUB_CLIENT_ID (public, baked into the bundle at build time), and
VITE_GITHUB_SCOPE=repo only for a classic OAuth App.
- Deploy. The function swaps the OAuth
code for a token and returns only the token; the client
secret never reaches the browser.
For local sign-in, copy web/.env.example to web/.env.local; npm run dev serves the same
function.
To redeploy from GitHub instead of Netlify's own Git integration, .github/workflows/deploy.yml
runs netlify deploy --build --prod on every push to main and on manual Run workflow. Add the
repo secrets NETLIFY_AUTH_TOKEN (a Netlify personal access token) and NETLIFY_SITE_ID; if
Netlify also builds from Git, turn that off so the two don't race.
The demo maps shipped with the site live in web/public/demo/. Add one with
GITHUB_TOKEN=... npm run demo -- owner/name 60, for a public repo only.
Project layout
AGENTS.md at the root is the map of the code, with a further AGENTS.md in each directory for
that layer's rules. In short: scan/ is the local scanner, web/src/ is the app (Three.js, no
framework), web/netlify/functions/ is the OAuth token exchange.
Security
See SECURITY.md to report a vulnerability.
License
MIT. The demo maps in web/public/demo/ are derived from third-party repositories under
their own licenses; see THIRD_PARTY_NOTICES.md.
