repo-atlas

Visualize any codebase as a 3D city. Files become buildings, directories become neighborhoods.

One command turns your codebase into an interactive 3D city you can explore in the browser. Building height = lines of code, building color = complexity (green to red). Click any building to see file stats.

repo-atlas ./my-project -o city.html

Why repo-atlas?

• Instant spatial intuition - See your entire codebase at once. Tall red buildings are complex hotspots. Clusters reveal architecture. You'll spot code smells in seconds.
• Self-contained HTML - Output is a single HTML file with Three.js loaded from CDN. No server needed. Share it, commit it, host it on GitHub Pages.
• Real metrics - Lines of code, cyclomatic complexity (estimated), import count, git blame data. Not just pretty -- actually useful.

Quickstart

pip install repo-atlas

# Visualize current directory
repo-atlas .

# Specify output and project name
repo-atlas ./my-project -o city.html --name "My Project"

# Show top 30 most complex files in terminal
repo-atlas . -v --top 30

# Open the result
open city.html

Features

• 3D interactive city: Three.js scene with orbit controls, zoom, pan
• Smart metrics: LOC, cyclomatic complexity, import count per file
• Git integration: Top contributor and last modified date from git blame
• Clickable buildings: Hover to see file stats, click to focus camera
• Search: Filter buildings by filename in real-time
• Color legend: Green (low complexity) to yellow to red (high complexity)
• Neighborhood grouping: Files grouped by directory on the ground plane
• Fog and lighting: Distance fog, ambient + directional + point lights
• Multi-language support: Python, JS/TS, Go, Rust, Java, Ruby, C/C++, and 30+ more

Architecture

Codebase Directory
       |
       v
  File Walker (respects .gitignore-style ignores)
       |
       v
  Metrics Analyzer (LOC, complexity, imports, git blame)
       |
       v
  City Layout Engine (grid neighborhoods, sorted placement)
       |
       v
  Three.js Renderer (self-contained HTML with inline data)
       |
       v
  city.html (open in any browser)

What the metrics mean

Metric	Building Property	Interpretation
Lines of Code	Height	Taller = more code
Cyclomatic Complexity	Color (green-red)	Redder = more branching logic
Import Count	Width/Depth	Wider = more dependencies
Directory	Neighborhood	Ground platform grouping

CLI Reference

Usage: repo-atlas [OPTIONS] [DIRECTORY]

Options:
  -o, --output TEXT    Output HTML file path (default: city.html)
  -n, --name TEXT      Project name (default: directory name)
  -v, --verbose        Show detailed file metrics in terminal
  -t, --top INTEGER    Show top N files by complexity (default: 20)
  --help               Show this message and exit.

Contributing

1. Fork the repository
2. Create a feature branch
3. Install dev dependencies: pip install -e ".[dev]"
4. Make changes and test: repo-atlas . -o test.html
5. Submit a pull request

License

MIT - see LICENSE for details.