An intelligent codebase visualizer. Point it at any repository — a Git URL or a local folder — and glide from a bird's-eye architectural map down to individual statement blocks, with cross-linked explanations at every level.
./run.sh # or: make runRequirements: Python 3.10+ and git on your PATH. That's it — the first run creates a virtualenv, installs pinned dependencies, starts the server on http://localhost:4870 and opens your browser. The frontend ships pre-built; Node is only needed if you want to hack on the UI.
The app self-demonstrates immediately with two built-in repositories:
- Orbit (sample) — a small, real task-tracker (Python server + JS web client + CLI). Every one of its 200+ units ships with a curated, cross-linked explanation, so the full experience works offline.
- CodeAtlas (this app) — the tool visualizing its own source.
Add your own repo via + Add repo (Git URL or absolute local path) — it's cloned shallowly and indexed in the background with live progress. A 600k-line repository (Django) indexes in about 5 seconds.
CodeAtlas builds a five-level hierarchy and lets you move through it fluidly:
| Level | Unit | Example |
|---|---|---|
| L4 | System | the whole repo: subsystems, dependency arrows, entry points |
| L3 | Module | a directory/package: purpose, key files, internal structure |
| L2 | File / class | responsibilities, members, collaborators |
| L1 | Function / method | contract, side effects, callers/callees |
| L0 | Statement block | line-level explanation inside a function |
Zoom in (scroll) or double-click and containers expand in place to reveal their internals — true semantic zoom that reveals/hides detail, not pixel scaling. Zoom out and they fold away again. Every explanation cross-references related units — callers, callees, imports, subclasses, parents — and every reference is a link that navigates and re-centers the map. Explanations are generated bottom-up (a module's summary synthesizes its files' summaries), so higher levels are grounded rather than hallucinated.
Panels: the zoomable map, a syntax-highlighted source view (an L1 function's blocks are clickable line-regions → L0 explanations), the explanation panel with cross-links and related-unit chips, a breadcrumb across levels, a file tree, and symbol search (⌕ box, arrow keys + Enter).
Explanations come from a pluggable Explainer with four backends, resolved in
this order:
- Anthropic — set
ANTHROPIC_API_KEY(model viaANTHROPIC_MODEL). - OpenAI-compatible — set
OPENAI_API_KEY; pointOPENAI_BASE_URLat OpenAI, Together, vLLM, LM Studio, or any compatible server (model viaOPENAI_MODEL). - Ollama — set
CODEATLAS_BACKEND=ollama(defaults:http://localhost:11434,qwen2.5-coder:7b). - Structural (offline) — always available, no network: real explanations derived from the AST and relationship graph (signatures, control flow, callers/callees, hotspots), clearly badged as structural.
You can also copy codeatlas.toml.example → codeatlas.toml. Environment
variables win over the file.
Caching: every explanation is cached on disk under data/cache/, keyed by
sha256(prompt_version | level | code-hash) — unchanged code is never
re-explained, which is what makes large repos affordable. Structural entries
are transparently upgraded the moment a live backend is configured (there's
also a ↻ button per unit). The sample's curated explanations live in the same
cache and are served by the same code path, so adding a key later changes
nothing except quality of new explanations. The live path for all three
protocols is exercised by scripts/verify_llm_backends.py against a mock
server.
Full AST parsing (bundled tree-sitter grammars, no network): Python, JavaScript, TypeScript/TSX, Java, Go, C, C++, Rust.
Best-effort symbol detection (regex): Ruby, PHP, C#, Swift, Kotlin, Scala,
shell, Lua, Perl, Elixir, R, Dart, SQL, Zig. Anything else still appears with
a structural file summary. Vendored/build directories (node_modules, dist,
venv, target, …), binaries, lockfiles and minified bundles are skipped
automatically; files stream in with progress so big repos never freeze the UI.
backend/codeatlas/
ingest.py clone/walk: skip-lists, binary sniff, size caps
languages.py grammar registry + per-language node-type specs
parsing.py tree-sitter extraction → files/classes/functions/blocks
linker.py import & call resolution (heuristic, precision-first)
indexer.py pipeline: parse → hierarchy → edges → SQLite (data/index/)
store.py SQLite store, one db per repo
explain/ Explainer interface, 4 backends, disk cache, context builder
main.py FastAPI: graph/tree/units/explanations/search + static UI
frontend/src/
components/Canvas.tsx semantic-zoom map (custom SVG, no graph lib)
lib/layout.ts nested dependency-column layout
… panels, breadcrumb, tree, search, theme
sample_repo/orbit/ the bundled demo codebase
scripts/ smoke tests, LLM-path verification, cache seeding
Notable choices (rationale in BUILD_LOG.md): SQLite over JSON for indexes;
official per-language tree-sitter wheels over runtime grammar downloads;
a hand-rolled SVG canvas + layered layout instead of a graph library (in-place
container expansion is the whole point); highlight.js over Monaco/Shiki.
Edges (calls, imports, inheritance) are stored at the finest level and aggregated on demand to whatever nodes are visible, so the arrows stay meaningful at every zoom depth.
make dev-frontend # Vite dev server with hot reload (proxies /api)
make build-frontend # rebuild frontend/dist
make smoke # API smoke test against the sample
python3 scripts/verify_llm_backends.py # mock-server test of the live path- Port busy —
CODEATLAS_PORT=5000 ./run.sh. - A repo fails to index — the progress overlay shows the error;
gitmust be on PATH for URL sources. - Corporate proxy breaks LLM calls — proxy env vars are honored when possible and bypassed when the proxy scheme is unsupported.
- Windows — run
python -m venv .venv && .venv\Scripts\pip install -r backend\requirements.txt && cd backend && ..\.venv\Scripts\python -m uvicorn codeatlas.main:app --port 4870(run.sh is macOS/Linux).
