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

City legend

Color coding

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