gitatlas

One map. Every repo. Down to the function.

Point it at a folder of repositories, or at a GitHub repo. Get one interactive HTML file that zooms from your whole system, to a repo, to a module, to a single function. No server, no cloud, no account. Your code never leaves your machine.

Real output: flask, click, and jinja in one map. 216 modules, 4,083 symbols, 6,679 edges.

Why

Agents write the code now. Somebody still has to understand it.

Writing code stopped being the bottleneck. Understanding a codebase you did not write, and increasingly that nobody wrote, is the expensive part. Your architecture diagram describes a company you no longer work at, and the one person who understood billing left in March.

gitatlas makes the map a file. One command, one HTML file, openable by anyone from the intern to the VP.

Related MCP server: CodeGraph

Quick start

Requires Node 22 or newer. No native builds, no database, no daemon.

npm install -g gitatlas        # or one-off: npx gitatlas extract /path/to/your/repos
gitatlas extract /path/to/your/repos

Open the index.html it prints at the end. That is the whole install. (About 60 MB on disk, dominated by the WASM grammars that cover 21 languages with zero native compilation.)

Or hand it a GitHub repo

No clone of your own required. Paste whatever spelling you have:

gitatlas extract expressjs/express
gitatlas extract https://github.com/expressjs/express
gitatlas extract git@github.com:expressjs/express.git

Pin a branch, a tag, or a commit with --ref, or paste the URL you were already looking at:

gitatlas extract expressjs/express --ref v4.18.2
gitatlas extract https://github.com/expressjs/express/tree/5.0    # the URL carries the ref

Each ref gets its own clone and its own map, named for it (express@v4.18.2), so mapping a branch never disturbs the map of the default branch, and the two can never be confused for each other. --ref wins over a ref in the URL, and says so when they disagree.

The repo is shallow-cloned to ~/.gitatlas/repos/<owner>/<repo> and the map lands in that clone, at the index.html path printed at the end. Later runs fetch into the same clone instead of downloading it again, which is what keeps gitatlas check and --if-stale meaningful against a moving upstream. Move the cache with --cache-dir or GITATLAS_CACHE_DIR, and use --out to put the map somewhere of your own.

Every other command takes the same target, so you never have to paste the cache path:

gitatlas brief --target expressjs/express
gitatlas scope --trace crash.txt --target expressjs/express
gitatlas mcp --target expressjs/express --ref v4.18.2   # pass the ref you extracted

A path that exists on disk always wins, so gitatlas extract owner/repo reaches for GitHub only when there is no such folder, and says so when it does. Credential prompts stay off, so a private repo works when your git can already read it non-interactively. The clone is shallow and skips submodules; docs/cli.md says what to do when you want them.

Working on gitatlas itself? The clone needs no build step:

git clone https://github.com/adityaarakeri/gitatlas && cd gitatlas
npm install
npm run extract -- fixtures && open fixtures/.gitatlas/index.html

What you get

Four zoom levels, and the camera flies between them.

Symbol level inside flask/app.py. Gold lines are calls: who actually invokes whom.

Neighborhoods are computed, not filed. Shaded regions group files that lean on each other and touch the rest lightly. When a utils file has quietly become load-bearing for billing, it shows up inside the billing neighborhood no matter which folder it lives in.

Hubs are where change ripples widest. A red ring marks the modules far above typical connection count. First place to look before a refactor, last place to edit casually on a Friday.

Every repo knows its own commit. Tap a repo at the group level and its detail panel shows the sha it was mapped at (full sha on hover), flagged if the working tree had uncommitted changes at extract time. brief, mcp, and gitatlas check --json carry the same commit, refName, and dirty state.

Press ⌘K and go anywhere. Type a few letters of any repo, file, class, or function across the entire group, and the camera flies to it. Hovering any node dims everything except its direct connections, so you can trace one module's wiring through a dense map without losing your place.

It opens in the reader's language. The map carries its UI in English, Chinese, Japanese, Spanish, and Portuguese, and picks one from the browser when it opens, with a picker beside the theme toggle. gitatlas extract --lang zh-CN pins the default instead. Only English is human-reviewed so far; docs/i18n.md has the status table and how to add a language. The graph data is unchanged either way, so nothing an agent reads depends on it.

Feed it to your coding agent

Agents are brilliant sprinters with amnesia. Every session yours greps around, rebuilds a mental model from scratch, and bills you for it. Hand it the map instead.

gitatlas brief --budget 1500     # token-budgeted markdown digest for a system prompt

claude mcp add gitatlas -- gitatlas mcp --out /path/to/repos/.gitatlas

brief, mcp, and scope also take --target <folder|github-repo> (with --ref if you pinned one), the same thing you handed extract, and find the map it wrote.

The MCP server exposes five tools over stdio: brief, scope (stack trace to ranked suspects), find_symbol, module_info, and check_freshness. It re-verifies source fingerprints before every answer, so an agent is never handed stale file:line data without a warning inside the result.

A map that has drifted from the code is worse than no map. gitatlas check exits 1 when anything is stale, and gitatlas extract --if-stale is the one-liner for CI jobs and agent hooks.

Details in docs/agents.md.

Three rules it will not break

1. The schema is the contract. Extractor and viewer never know about each other.

2. Artifacts are files. No daemon, no database, no required network. Handing it a GitHub repo is the one time it dials out, and only because you asked it to.

3. Every edge carries confidence. exact, resolved, or inferred. Guesses are drawn dashed and labeled. Nothing is upgraded to a fact.

Nothing comes from a language model. When helper() could be three different symbols, gitatlas emits no edge rather than a wrong one. Same repos in, pixel-identical map out, every run.

How it compares

Hand-written models drift the day their author goes on holiday. This one regenerates from the code.

Commands

Full flags, repo discovery, GitHub targets and refs, submodule modes, and ignore globs: docs/cli.md.

Honest limitations

• 21 languages, but call edges resolve in 14 of them so far. The rest still get symbols, imports, and inheritance.

• No cross-repo edges yet. Repo A calling repo B over HTTP is invisible to static analysis. The boundary stitcher is next.

• Unused-symbol rings are a hint, not a verdict. Matching is name-based and repo-local, so a function consumed from another repo looks lonelier than it is.

• The viewer's fonts load from Google Fonts. d3 is vendored in, so the map itself renders offline. Only the type falls back to system faces.

The full list, including the Node 24 V8 flag and per-language privacy conventions, is in docs/internals.md.

Put it in every repo

Every repo should ship with its own map, the same way it ships with a README.

Copy examples/github-action.yml into .github/workflows/gitatlas.yml and every push to main regenerates the map as a downloadable artifact. Point the upload step at GitHub Pages instead and it becomes a URL your team can bookmark.

Roadmap

Next: the cross-repo stitcher (HTTP routes and clients, queue topics, shared-package joins), a per-repo touchpoint inventory (env vars, databases, third-party SDKs), watch mode with incremental re-extraction, and proper multi-level clustering if large repos show fragmented neighborhoods.

Already shipped: call edges (0.9.0), precomputed deterministic layout and the command palette (0.8.0), 21 languages (0.7.0), neighborhoods and hubs (0.6.0), the scope bug scoper (0.4.0).

Docs

• docs/cli.md - every command and flag

• docs/agents.md - brief, MCP, and freshness

• docs/internals.md - architecture, determinism, limitations, prior art

• docs/playground.md - hosted site and cheap deploys

Contributing

Read CONTRIBUTING.md. The most valuable contribution right now is a new language extractor, and the doc walks through exactly what one has to emit.

License

MIT