🗺️ codeatlas

Map any codebase to one pretty, self-contained HTML file — in a single command.

Zero dependencies · no build step · works offline · drop it anywhere

▶️ Try the live demo (no install, runs in your browser)

requests — 102 files mapped · codeatlas mapping itself

---

codeatlas turns a folder into a visual, interactive atlas of your code — a donut chart of the language mix, a collapsible source tree with sizes, and a "biggest files / refactor candidates" list. All of it is rendered into one single, dependency-free HTML file that you can open offline, email to a teammate, or drop into GitHub Pages.

🎯 Why you'll love it: in seconds you can see what a repo is made of, which files are huge monsters begging for a refactor, and where the real code lives — before reading a single line.

If you find this useful, a ⭐ is the fastest way to support it. 🙏

---

✨ Features

🎨 One command	codeatlas ./my-repo → done. That's it.
📦 Zero dependencies	stdlib only. Works on any Python 3.8+. No npm, no node, nothing to install.
📄 Self-contained output	A single .html file. No CDNs, no external JS/CSS/fonts. Works fully offline.
📊 Language donut	Instantly see the language/byte mix with a clean SVG donut + legend.
🌳 Interactive source tree	Collapsible tree of every folder & file with sizes (no JS required).
🔍 Refactor radar	The biggest files, sorted — your top candidates for a cleanup.
⚡ Fast & safe	Reads your .gitignore, plus extra -i rules on the fly.
🧪 Real dogfooding	This very repo maps itself. The output you see was generated by codeatlas.
🧬 --json	Machine-readable metrics for scripts, dashboards & CI.
📛 --badge	A GitHub-profile-style language bar SVG for your own README.
🌐 --open	Write the atlas and pop it straight into your browser.

---

🚀 Quick start

# No pip needed — just clone & run:
python codeatlas.py path/to/your/repo

# ...or install it properly:
pip install -e .
codeatlas path/to/your/repo

The default output is <repo>-atlas.html. Pick your own path and open it instantly:

codeatlas ./my-project -o my-atlas.html --open

Want JSON instead of a pretty page?

codeatlas ./my-project --json
codeatlas ./my-project --badge -o language-bar.svg   # for your README

Or skip anything you don't care about:

codeatlas ./big-repo -i "*.lock" -i "generated/"

As a Python library

from codeatlas import render, scan

stats = scan.scan("./my-project")
page  = render.render(stats)

with open("atlas.html", "w", encoding="utf-8") as f:
    f.write(page)

---

📸 It looks like this

Everything below is real output produced by codeatlas. Open the .html files directly in your browser — they are single files and work perfectly offline.

🗺️ requests-atlas.html — the famous requests library (102 files · 18,614 LOC) mapped in one command:

🪞 Dogfooding: codeatlas-atlas.html — this very repository mapped by itself:

---

📦 How it works

1. Scan — walks the directory tree (stdlib only), honouring your .gitignore and skipping node_modules, .git, dist, build, dotfiles, caches, etc.
2. Classify — detects 40+ languages/extensions by name and gives each a stable, pretty colour.
3. Measure — counts files, bytes and lines-of-code per folder & language.
4. Render — emits one self-contained HTML page: donut chart, collapsible tree, biggest-files radar.

The language mix of this very repository, generated with codeatlas --badge:

The whole thing is a few hundred lines of clean, readable Python with zero dependencies — small enough to read and hack on in an afternoon.

---

🗂️ Repository layout

codeatlas/
├── codeatlas/
│   ├── __init__.py
│   ├── __main__.py        # python -m codeatlas
│   ├── cli.py             # the command line interface
│   ├── scan.py            # filesystem walker + statistics model
│   ├── render.py          # self-contained HTML generation
│   └── languages.py       # language detection + colour palette
├── tests/                 # pytest suite
├── examples/              # generated demo atlases (dogfooded)
├── docs/assets/           # screenshots for this README
├── pyproject.toml
└── README.md

---

🛣️ Roadmap (want to help?)

• CLI + self-contained HTML output
• Language donut, tree, biggest-files
• Dogfooding example
• --json output for CI / pipelines
• .gitignore support + -i extra rules
• --badge line-of-code language bar for READMEs
• File-type heatmap / treemap view
• --diff to compare two versions of a repo
• GitHub Action that auto-publishes a repo's atlas to Pages
• NPM/homebrew install shims for the non-Python folks

Ideas, bugs, and PRs are very welcome. If you use it, a ⭐ is the best way to say thanks!

---

🤝 Contributing

1. Fork it
2. Create your feature branch (git checkout -b feat/amazing)
3. Commit your changes
4. Push & open a Pull Request

pip install -e .
python -m pytest        # run the tests

---

📄 License

MIT © codeatlas contributors. Go build something great.