code-atlas 0.1.0

Render local code repositories as architectural treemaps with line-addressed, hierarchically bundled call graphs
Documentation

Code Atlas

CI crates.io docs.rs license

Renders an architectural map for a code repo. Files and directories are renderes on a treemap, overlayed by (method/function) calls between them as a hierarchical edge bundled callgraph.

light dark
Wasmex calls in the light theme Wasmex calls in the dark theme

Reading the map

  • Treemap parcel area represents lines of code, byte size, or commit count.
  • Every visible route is one callsite. A route begins at the source line's position inside its file, follows the directory hierarchy, and ends at the target line.
  • Color shows direction: red at the source, blue at the target. Call routes get more intense in color when they overlap. This allows to see main communication routes in a project.

Install

Code Atlas supports Linux and macOS and requires Git at runtime. Installing from source requires Rust 1.87 or newer.

cargo install code-atlas --locked

Checksummed native archives are also attached to tagged GitHub releases.

Try it

Create a self-contained interactive viewer from any local checkout:

code-atlas render \
  --repo /path/to/checkout \
  --output atlas.html \
  --width 1920 --height 1080 \
  --exclude assets --exclude docs --exclude guides

Open atlas.html directly or put that single file on any static host. It embeds the map, calls, light and dark themes, filters, and viewer code; it makes no runtime network requests.

Create an A2 landscape poster with a higher-resolution call layer:

code-atlas render \
  --repo /path/to/checkout \
  --output atlas.pdf \
  --width 7016 --height 4961 \
  --theme night --backend wgpu \
  --pdf-dpi 300 --pdf-call-dpi 600 \
  --resume

The output extension selects PNG, SVG, PDF, or HTML. SVG and PDF keep parcels, boundaries, and labels as vectors. PDF calls are rendered in bounded tiles; --resume verifies and reuses completed tiles after interruption.

Useful controls:

Option Meaning
--metric loc|bytes|commits Choose the file-area metric.
--theme architect|night|ink|solarized-dark|solarized-light Choose the static-output appearance. HTML always embeds light and dark.
--backend software|wgpu Choose the call renderer. Unsupported GPUs fall back to software.
--exclude PATH Exclude a repository-relative prefix; repeat as needed.
--include-tests Include conventional test paths, excluded by default.
--include-hidden Include dotfiles and dot-directories, excluded by default.

Run code-atlas render --help for every layout, pigment, and print option.

Explore calls in the browser

Pan and zoom like a map, select a file or individual spline, and filter calls without collapsing them. The query language is case-insensitive:

in:*delivery*
out:*attempts* in:*delivery*
path:*clickhouse* -in:*deprecated*
in:*delivery* | in:*authoring*

in:/to: match target paths, out:/from: source paths, and path: either endpoint. callee: and analyzer: match call metadata. Spaces mean AND, | means OR, and a leading - excludes a term. The viewer includes examples and specific syntax-error help.

Selection, query, and camera position are stored in the URL hash for sharing. Appearance follows the system by default and can be saved as Light or Dark. WebGPU is used when available, with a Canvas2D fallback; pigment automatically strengthens when filters leave only a few visible calls.

Source and target lines can link back to a hosted repository:

code-atlas render \
  --repo /path/to/checkout \
  --output atlas.html \
  --source-url-template \
    'https://github.com/OWNER/REPO/blob/{revision}/{path}#L{line}'

Analyzer coverage

Language Preferred analysis Fallback
Elixir mix xref trace conservative parsing for scripts
Rust rust-analyzer SCIP uniquely resolved syntax calls
TypeScript / JavaScript scip-typescript relative-import calls
Gleam explicit-import resolution -

Use CODE_ATLAS_RUST_ANALYZER or CODE_ATLAS_SCIP_TYPESCRIPT to override the semantic indexer binaries. Code Atlas never downloads analyzer tools while rendering. Inspect coverage and warnings without producing an image:

code-atlas inspect --repo /path/to/checkout

"Every call" means every cross-file callsite resolved by the active analyzers. Dynamic dispatch, macros, reflection, and generated code prevent any static tool from seeing every runtime call. Same-file calls are intentionally excluded. The JSON report records analyzer coverage, unresolved calls, exclusions, the Git revision, dirty-worktree state, renderer, and timing information.

Security and privacy

Only analyze repositories and language toolchains you trust: semantic analysis may run project-local tools such as mix compile. HTML exports contain no source text, but they do contain paths, revision identifiers, metrics, call metadata, and geometry. Treat private-repository exports as sensitive project metadata. See SECURITY.md for the full boundary and reporting process.

Development

The CLI is the supported interface. The Rust library remains experimental during the 0.x series. See CONTRIBUTING.md for local checks and RELEASING.md for the release procedure.

This project was built through LLMs.

License

Code Atlas is released under the MIT License.