codeasciimap 1.0.0

Navigate any codebase or GitHub repo as a real-time ASCII city in your terminal

CodeASCIIMap

Walk around any codebase — or any GitHub repo — as a live ASCII city inside your terminal.

  ╔══════════════ facebook/react ═══════════════╗
  ║                                             ║
  ║  ┌──────────┐  ┌────────────────────┐       ║
  ║  │▓▓▓▓▓▓▓▓▓▓│  │▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│       ║
  ║  │░░░ ░░░ ░░│  │░░░ ░░░ ░░░ ░░░ ░░░░│       ║
  ║  │░░░ ░░░ ░░│  ├────────────────────┤       ║
  ║  └─index.js─┘  │░░░ ░░░ ░░░ ░░░ ░░░░│       ║
  ║                └─ReactDOM.js─────── ┘       ║
  ╚═════════════════════════════════════════════╝
          ─────────────────────────────
                       @

Each directory is a walled city block. Each file is a building — taller buildings have more lines. Walk around with WASD, search with /, and inspect any file's source code by pressing i.

---

Install

pip install codeasciimap

On Windows, windows-curses is installed automatically as a dependency.

---

Run

# Current directory
codeasciimap

# Any local path
codeasciimap ~/projects/myapp
codeasciimap C:\Users\you\projects\myapp

# GitHub repo  (owner/repo shorthand)
codeasciimap torvalds/linux
codeasciimap facebook/react
codeasciimap twbs/bootstrap
codeasciimap vercel/next.js

# Full GitHub URL
codeasciimap https://github.com/django/django

GitHub repos are shallow-cloned (--depth 1 --filter=blob:none) so even massive repos like the Linux kernel load in seconds. The clone is deleted automatically when you quit.

---

Controls

Key	Action
W A S D or arrow keys	Move around the city
i or Enter	Inspect the file you're standing next to
j / k	Scroll file content up/down in inspector
q or Esc	Close inspector / cancel search
/	Open search bar
Enter	Jump to search result
n / N	Next / previous search result
? or F1	Show help screen
q or Ctrl+C	Quit

---

City legend

Symbol	Meaning
@	You (the player)
╔═╗ ║ ╚═╝	District border (a directory)
┌─┐ │ └─┘	Building frame (a file)
▓	Penthouse / top floor
░░░ ░░░	Window floors (lit office at night)
├───┤	Floor separator (every 3 floors)
│ above building	Rooftop antenna (tall buildings only)
─ / │ / ·	Streets

Color coding

Color	Lines
🟢 Green	< 50 lines
🟡 Yellow	50 – 500 lines
🔴 Red	500 – 2 000 lines
🔵 Cyan	> 2 000 lines
🟣 Magenta	Binary or unreadable

---

Mini-map

The bottom-right corner always shows a miniature overview of the entire city. Your position blinks as @. The dotted rectangle shows what's currently on screen.

---

Requirements

• Python ≥ 3.8
• git on PATH (only needed for GitHub repos)
• Terminal ≥ 80 × 24, UTF-8 recommended

---

Publish to PyPI (maintainers)

pip install build twine
python -m build
twine upload dist/*

Then anyone in the world can install with:

pip install codeasciimap